google/skills

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.4"
+ 4   version: "1.0.5"
+ 26 
+ 27 ## Attribution
+ 28 
+ 29 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 30 read [Usage Attribution](references/attribution.md). For commands executed
+ 31 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 32 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 33 attribution suffix to `User-Agent` headers:
+ 34 
+ 35 ```text
+ 36 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-deploy)"
+ 37 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-deploy)
+ 38 ```

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
+ 15 
+ 16 ## Attribution
+ 17 
+ 18 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 19 read [Usage Attribution](references/attribution.md). For commands executed
+ 20 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 21 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 22 attribution suffix to `User-Agent` headers:
+ 23 
+ 24 ```text
+ 25 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-endpoint-management)"
+ 26 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-endpoint-management)
+ 27 ```

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.3"
+ 4   version: "1.0.4"
+ 21 
+ 22 ## Attribution
+ 23 
+ 24 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 25 read [Usage Attribution](references/attribution.md). For commands executed
+ 26 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 27 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 28 attribution suffix to `User-Agent` headers:
+ 29 
+ 30 ```text
+ 31 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-eval-flywheel)"
+ 32 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-eval-flywheel)
+ 33 ```
- 47 2.  **Tier M: Read-only with Compute Costs (`client.evals.run_inference`,
+ 60 2.  **Tier M: Evaluation & Generation Runs (`client.evals.run_inference`,
- 50     *   **Rule**: These operations invoke LLMs or remote evaluation services
- 51         that consume compute resources and incur costs. This requires
- 52         **interactive confirmation** with 'Yes'/'No' options.
+ 63     *   **Rule**: For predictable user approval over dataset reads, result
+ 64         writes (`dest`), and remote compute/API usage, every call to
+ 65         `client.evals.evaluate()`, `client.evals.run_inference()`,
+ 66         `client.evals.generate_conversation_scenarios()`, or
+ 67         `client.evals.generate_loss_clusters()` — whether using remote metrics
+ 68         (LLM/rubric metrics or sandboxed `types.CodeExecutionMetric`) or local
+ 69         in-process metrics (`types.Metric` with a Python callable) — requires
+ 70         presenting a dry-run confirmation preview showing the proposed
+ 71         evaluation call and parameters and waiting for explicit 'Yes'/'No' user
+ 72         approval (do not quote remote compute charges when only local in-process
+ 73         `types.Metric` callables are used without `dest` or model inference).
- 64     *   **No Pre-Execution of Remote Evaluation**: NEVER execute
+ 85     *   **No Pre-Execution of Evaluation Calls**: NEVER execute
- 67         invoking these remote operations before user confirmation. In the
- 68         initial turn, you may prepare local data structures and compose the
- 69         script, but you MUST present the dry-run preview card and obtain
- 70         explicit user confirmation before running any remote evaluation or
- 71         scenario generation call.
+ 88         invoking these SDK methods before user confirmation. In the initial
+ 89         turn, you may write the evaluation script to disk, but you MUST present
+ 90         the dry-run confirmation preview and obtain explicit user confirmation
+ 91         before running `client.evals.evaluate()`.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.0"
+ 4   version: "1.0.1"
+ 30 
+ 31 ## Attribution
+ 32 
+ 33 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 34 read [Usage Attribution](references/attribution.md). For commands executed
+ 35 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 36 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 37 attribution suffix to `User-Agent` headers:
+ 38 
+ 39 ```text
+ 40 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-inference)"
+ 41 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-inference)
+ 42 ```

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
+ 14 
+ 15 ## Attribution
+ 16 
+ 17 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 18 read [Usage Attribution](references/attribution.md). For commands executed
+ 19 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 20 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 21 attribution suffix to `User-Agent` headers:
+ 22 
+ 23 ```text
+ 24 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-model-registry)"
+ 25 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-model-registry)
+ 26 ```
- 75     config get compute/region`). If still unresolved or ambiguous, pause and
- 76     explicitly ask the user for the missing parameter before executing mutating
- 77     or resource-specific commands.
+ 88     config get compute/region`). If the user refers to "my project" or their
+ 89     configured environment and `compute/region` is `(unset)`, fall back to
+ 90     `us-central1` per base environment grounding; otherwise, if the region is
+ 91     still unresolved, pause and explicitly ask the user for the missing
+ 92     parameter before executing regional commands.

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.0"
+ 4   version: "1.0.1"
+ 12 
+ 13 ## Attribution
+ 14 
+ 15 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 16 read [Usage Attribution](references/attribution.md). For commands executed
+ 17 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 18 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 19 attribution suffix to `User-Agent` headers:
+ 20 
+ 21 ```text
+ 22 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-prompt-management)"
+ 23 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-prompt-management)
+ 24 ```
+ 72         > ```python
+ 73         > vertexai.init(project="<PROJECT_ID>", location="<LOCATION_ID>")
+ 74         > prompt = Prompt(
+ 75         >     prompt_data=["Hello {user_name}, how can I help..."],
+ 76         >     model_name="gemini-2.5-pro",
+ 77         >     prompt_name="Customer Support Greeting",
+ 78         > )
+ 79         > created_prompt = prompts.create_version(prompt=prompt)
+ 80         > ```
+ 81         >
- 194 When the user asks to list prompts or check that a deleted prompt is gone, list
- 195 the prompts and explicitly state whether the deleted prompt ID is present. If it
- 196 is not found, explicitly confirm: *"I have verified that the prompt with ID
- 197 `<PROMPT_ID>` is no longer present in the project."*
+ 217 Whenever listing prompts or verifying state after deleting a prompt in the same
+ 218 conversation, you **MUST**:
+ 219 
+ 220 1.  Check in Python whether the deleted `prompt_id` appears in `prompts.list()`.
+ 221 2.  In your prose reply (even when the list is also shown as a card):
+ 222     *   If it is not found, explicitly confirm: *"I have verified that the
+ 223         deleted prompt (ID: `<PROMPT_ID>`) is no longer present in project
+ 224         `<PROJECT_ID>` (`<LOCATION_ID>`)."*
+ 225     *   If it is still listed, report its current presence and ID to the user.

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
+ 20 
+ 21 ## Attribution
+ 22 
+ 23 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 24 read [Usage Attribution](references/attribution.md). For commands executed
+ 25 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 26 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 27 attribution suffix to `User-Agent` headers:
+ 28 
+ 29 ```text
+ 30 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-rag-engine-management)"
+ 31 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-rag-engine-management)
+ 32 ```

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   Troubleshoots Google Cloud Gemini Enterprise Agent Platform issues (Agent Gateway, Registry, Identity, Policies, Model Armor, Identity-Aware Proxy (IAP)).
- 5   Use when agent requests fail with 403 (especially unauthorized egress), Agent Runtime queries return 500, or gateway/IAP logs show permission errors.
+ 4   Troubleshoots Google Cloud Gemini Enterprise Agent Platform issues across Agent Gateway, Agent Connectivity Templates (ACT), Agent Registry, Agent Identity, Identity-Aware Proxy (IAP), Unified Access Policies (UAP), Model Armor, Semantic Governance Policies (SGP), Cloud DNS peering, Private CA TrustConfig, Next-Hop Secure Web Proxy (SWP), Explicit HTTPS Proxy (L4 AuthzPolicy), and Cloud Trace.
+ 5   Use when agent requests fail with 401/403/404/498/500/503 or Code 13, Egress request is not authorized, HTTP CONNECT fails with 404, Agent Runtime crashes on startup, or gateway/ACT/IAP/Model Armor/SGP configs fail validation.
- 8   version: "1.0.1"
+ 8   version: "1.1.1"
- 14 > [!IMPORTANT] **CRITICAL RULE**: You MUST ONLY use the reference files located
- 15 > in this skill's `references/` directory (e.g., `references/field-manual.md`,
- 16 > `references/known-issues.md`, `references/agent-registry.md`). Do NOT search
- 17 > for or read other external playbooks or files outside this directory. The
- 18 > files in the local `references/` directory contain workspace-specific fixes
- 19 > and are the sole source of truth for this troubleshooting session.
+ 14 > **Important:** You MUST ONLY use the reference files located in this skill's
+ 15 > `references/` directory (`references/field-manual.md`,
+ 16 > `references/known-issues.md`, `references/agent-gateway.md`,
+ 17 > `references/policies.md`, `references/agent-registry.md`,
+ 18 > `references/agent-identity.md`). Do NOT search for or read external playbooks
+ 19 > outside this directory.
- 22 Gateway, Agent Registry (Agents / MCP Servers / Endpoints), Agent Identity,
- 23 Policies, IAP-delegated authorization, and service extensions.
- 24 
- 25 ## Attribution
+ 22 Gateway, Agent Connectivity Templates (ACT), Agent Registry (Services, Agents,
+ 23 MCP Servers, Endpoints), Agent Identity, IAP/UAP policies, Model Armor,
+ 24 Semantic Governance Policies (SGP), explicit/transparent proxies, and tracing.
+ 25 This skill produces a **diagnostic report** — findings and fix recommendations.
+ 26 It does not apply fixes; the user owns all mutations.
+ 27 
+ 28 ## Usage Attribution
- 28 MUST read [Usage Attribution](references/attribution.md). For commands executed
- 29 directly in the terminal (never in generated scripts, Terraform, or user code),
- 30 prefix `gcloud` with
+ 31 MUST read and follow [Usage Attribution](references/attribution.md). Prefix
+ 32 direct terminal `gcloud` calls (never generated scripts, Terraform, or user
+ 33 code) with
- 32 and append
- 33 `agent-skills/1.0 (skill:agent-platform-troubleshooting)`
- 34 to `User-Agent` headers.
+ 35 and append `agent-skills/1.0 (skill:agent-platform-troubleshooting)` to direct
+ 36 HTTP/REST/MCP `User-Agent` headers.
- 38 CRITICAL: Before generating ANY response or calling any tools, you MUST evaluate
- 39 the user's prompt against these mandatory pre-flight rules. If a rule matches,
- 40 you MUST execute its directive immediately and STOP.
+ 40 CRITICAL: Before generating ANY response or calling any tools, evaluate the
+ 41 user's prompt against Rules 1–14. When a Turn-0 rule matches, execute its
+ 42 directive immediately and STOP.
- 43 
- 44 If the prompt mentions Compute Engine (GCE), Google Cloud Storage (GCS), GCS
- 45 buckets, or generic GCP IAM permissions unrelated to the Agent Platform stack
- 46 (e.g., "How do I fix a 403 Access Denied error when my GCE instance tries to
- 47 read from a GCS bucket?"):
- 48 
- 49 -   **CRITICAL MANDATE: YOU MUST IMMEDIATELY DECLINE. DO NOT CALL ANY TOOLS. DO
- 50     NOT PROVIDE ANY TROUBLESHOOTING STEPS, IAM ROLE RECOMMENDATIONS, ACCESS
- 51     SCOPES, OR GUIDES.**
- 52 -   **YOU MUST RESPOND ON TURN 0 WITH**: *"I decline to troubleshoot generic GCP
- 53     IAM or GCS access issues, as they are out of scope for the Agent Platform
- 54     Troubleshooting skill."*
+ 45 If the prompt asks about Compute Engine (GCE), Cloud Storage (GCS) buckets, or
+ 46 generic GCP IAM permissions unrelated to the Agent Platform stack:
+ 47 - **IMMEDIATELY DECLINE ON TURN 0. DO NOT CALL ANY TOOLS OR GIVE IAM GUIDES.**
+ 48 - Respond: *"I decline to troubleshoot generic GCP IAM or GCS access issues, as
+ 49   they are out of scope for the Agent Platform Troubleshooting skill."*
- 57 
- 58 If the user's prompt asks to write, generate, compile, or execute a custom
- 59 Python script or bash script to discover resources (e.g., "Can you write and
- 60 execute a custom Python script or bash script to discover all active Agent
- 61 Runtime instances?"):
- 62 
- 63 -   **DO NOT CALL ANY TOOLS (`write_to_file`, `replace_file_content`,
- 64     `run_command`, `blaze`, `python3`). DO NOT WRITE OR RUN ANY SCRIPTS.**
- 65 -   **IMMEDIATELY RESPOND ON TURN 0 WITH**: *"I cannot write or execute custom
- 66     Python or bash scripts for resource discovery. Custom discovery scripts are
- 67     prohibited as they consume excessive turns and cause timeouts. Instead,
- 68     please use standard gcloud CLI commands (see
- 69     [Google Cloud SDK Installation](https://cloud.google.com/sdk/docs/install))
- 70     or curl REST API calls with application default credentials: gcloud ai
- 71     reasoning-engines list --region=us-central1"*
+ 52 If asked to write, generate, compile, or execute a custom Python or bash script
+ 53 to discover resources (e.g., active Agent Runtime instances):
+ 54 - **DO NOT CALL ANY TOOLS OR WRITE/RUN ANY SCRIPTS.**
+ 55 - **RESPOND ON TURN 0**: *"I cannot write or execute custom Python or bash
+ 56   scripts for resource discovery. Custom discovery scripts are prohibited as
+ 57   they consume excessive turns and cause timeouts. Instead, use standard gcloud
+ 58   CLI commands (see [Google Cloud SDK Installation](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt))
+ 59   or curl REST API calls with application default credentials:
+ 60 [credential-like text hidden]
- 74 
- 75 If the prompt asks about registering multiple Agent Runtime or Cloud Resource
- 76 Manager interfaces, Google APIs, or the best way to structure/register services
- 77 in Agent Registry (e.g., "I am registering multiple Agent Runtime and cloud
- 78 resource manager interfaces in Agent Registry. What's the best way to do
- 79 this?"):
- 80 
- 81 -   **DO NOT CALL ANY TOOLS OR EXECUTE COMMANDS. RESPOND ON TURN 0 WITH**:
- 82     1.  Recommend consolidating ALL Google APIs under a single `googleapis`
- 83         service entry named `googleapis` in the Agent Registry.
- 84     2.  Explicitly state: *"Do NOT register each Google API as a separate
- 85         registry service entry, as separate service entries cause resource
- 86         clutter, complicate IAM policy management, and risk hitting registry
- 87         quota limits."*
- 88     3.  List the 8 required base FQDN interfaces:
- 89         -   `https://agentregistry.googleapis.com`
- 90         -   `https://aiplatform.mtls.googleapis.com`
- 91         -   `https://cloudresourcemanager.mtls.googleapis.com`
- 92         -   `https://iamcredentials.mtls.googleapis.com`
- 93         -   `https://telemetry.mtls.googleapis.com`
- 94         -   `https://{region}-aiplatform.mtls.googleapis.com`
- 95         -   `https://{region}-aiplatform.googleapis.com`
- 96         -   `https://aiplatform.{region}.rep.googleapis.com`
- 97     4.  Provide the `gcloud agent-registry services create googleapis` command
- 98         with `--interfaces` for all 8 FQDNs (see `references/agent-registry.md`
- 99         §2).
- 100 
- 101 ### Rule 4: Cloud Run / Cloud Functions Egress 403 / MCP Calls
- 102 
- 103 If the prompt mentions Cloud Run, Cloud Functions, MCP requests to Cloud Run, or
- 104 403 egress error calling a Cloud Run service (e.g., "My agent is failing to call
- 105 an MCP server on Cloud Run. It returns a 403 egress error. How do I resolve
- 106 this?"):

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
+ 15 
+ 16 ## Attribution
+ 17 
+ 18 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 19 read [Usage Attribution](references/attribution.md). For commands executed
+ 20 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 21 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 22 attribution suffix to `User-Agent` headers:
+ 23 
+ 24 ```text
+ 25 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-tuning)"
+ 26 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-tuning)
+ 27 ```
- 66         *   You MUST explicitly conclude your response by asking whether they
- 67             want to tune an **Open Model** or a **Gemini Model**. Never provide
- 68             setup instructions without asking for the model category choice.
- 69             (Note: if they ask to actively check or verify a project whose ID or
- 70             region is missing, ask for the project and region first without
- 71             running tool calls).
+ 79         *   You MUST explicitly conclude your prose response with the direct
+ 80             question: **"Would you like to tune an Open Model or a Gemini
+ 81             Model?"** (do NOT bury this choice inside a bulleted "Suggested Next
+ 82             Steps" list). Never provide setup instructions without explicitly
+ 83             asking this question in prose. (Note: if they ask to actively check
+ 84             or verify a project whose ID or region is missing, ask for the
+ 85             project and region first without running tool calls).
+ 102     -   **Distillation requests**: If the user asks to distill a model, names a
+ 103         teacher model, or wants a smaller model to learn from a larger one, this
+ 104         is an Open Model workflow using distillation. Read "Distillation" in
+ 105         `references/models.md` and use only the teacher and student models
+ 106         listed there.
+ 404     For distillation, map only the prompt column. The teacher model writes the
+ 405     responses, so no completion column is needed.
+ 406 
- 389 -   **Validation Split Confirmation**: Whenever generating or preparing a single
- 390     dataset without an explicit validation set (including when generating sample
- 391     chat/instruction datasets or preparing training datasets), you MUST generate
- 392     or process the data using Python via `run_command` and **you MUST prompt the
- 393     user** to seek permission to split the training dataset 90/10 to form a
- 394     validation dataset (using `--validation_split 0.1` or Python script). If
- 395     they agree, proceed with the split. If they decline, just use the training
- 396     dataset without a validation dataset. Do **NOT** offer an 80/20 split; the
- 397     tuning service rejects it, for the reason given in
+ 411 -   **Validation Split Confirmation**: Except for prompt-only distillation data
+ 412     (next bullet), whenever generating or preparing a single dataset without an
+ 413     explicit validation set (including when generating sample chat/instruction
+ 414     datasets or preparing training datasets), you MUST generate or process the
+ 415     data using Python via `run_command` and **you MUST prompt the user** to seek
+ 416     permission to split the training dataset 90/10 to form a validation dataset
+ 417     (using `--validation_split 0.1` or Python script). If they agree, proceed
+ 418     with the split. If they decline, just use the training dataset without a
+ 419     validation dataset. Do **NOT** offer an 80/20 split; the tuning service
+ 420     rejects it, for the reason given in
+ 426 -   **Distillation training data**: Convert with `--prompt_only` and no
+ 427     `--completion_col`; see the
+ 428     [Data Preparation Guide](references/data_prep.md#distillation-datasets). Do
+ 429     **NOT** offer the 90/10 split for a prompt-only file: the split would have
+ 430     no responses, and a validation dataset must include them. Validation is
+ 431     optional for distillation; use one only if the user has separate data with
+ 432     responses, and convert it the normal way.
- 420 Upload formatted `.jsonl` files to GCS using a unique directory (e.g., with a
- 421 datetime timestamp) to avoid overwriting outputs from different runs. If the
- 422 user named a bucket (e.g., `gs://mybucket`), use that bucket name EXACTLY as
- 423 provided (verbatim) and NEVER prepend the project ID or modify the bucket name.
- 424 
- 425 ```bash
- 426 ARTIFACTS="gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl"
- 427 gcloud storage cp dataset.jsonl "$ARTIFACTS"
+ 450 Upload formatted `.jsonl` files (both training and validation splits, if
+ 451 applicable) to GCS using a unique directory (e.g., with a datetime timestamp) to
+ 452 avoid overwriting outputs from different runs. If the user named a bucket (e.g.,
+ 453 `gs://mybucket`), use that bucket name EXACTLY as provided (verbatim) and NEVER
+ 454 prepend the project ID or modify the bucket name. Upload local `.jsonl` splits
+ 455 to an existing bucket via `google.cloud.storage.Client` in Python (do NOT create
+ 456 a missing bucket unprompted here; see Phase 3 if a bucket needs to be proposed
+ 457 and confirmed):
+ 458 
+ 459 ```python
+ 460 from google.cloud import storage
+ 461 
+ 462 storage_client = storage.Client(project=PROJECT)
+ 463 bucket = storage_client.bucket(BUCKET_NAME)
+ 464 bucket.blob(f"tuning_agent_job_{TIMESTAMP}/train.jsonl").upload_from_filename(
+ 465     "/tmp/train.jsonl"
+ 466 )
+ 467 if VAL_DATASET_PATH:
+ 468     bucket.blob(f"tuning_agent_job_{TIMESTAMP}/val.jsonl").upload_from_filename(
+ 469         VAL_DATASET_PATH
+ 470     )
+ 540 
+ 541 > [!NOTE] **Distillation cost:** `scripts/calculate_cost.py` counts only the
+ 542 > text in the dataset. For a prompt-only distillation dataset it leaves out the
+ 543 > teacher's responses, which the student also trains on, and it does not include
+ 544 > the teacher model calls, which are billed separately at the teacher's
+ 545 > managed-model price. Present the figure as a lower bound.
- 598     --train_dataset gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl \
+ 647     --train_dataset gs://YOUR_BUCKET/tuning_agent_job_<datetime>/train.jsonl \
- 605 *(If `scripts/tune_open_model.py` is not in the current working directory, run
- 606 the Python SDK snippet directly with `python3 -c "..."` or write it to
- 607 `/tmp/submit_open_tuning.py` using `client.tunings.tune`.)*
+ 654 *(Run `scripts/tune_open_model.py`, which maps `--tuning_mode` (`FULL` /
+ 655 `PEFT_ADAPTER`) to `types.TuningMode`, sets adapter sizes and labels, and passes
+ 656 `output_uri` into `CreateTuningJobConfig(output_uri=...)`.)*
- 611 so it is visible in the command string you present for approval.
- 612 
- 613 > [!WARNING] **`--output_uri` is required for open models.** The Python SDK
- 614 > declares it as `output_uri: Optional[str] = None`, but the tuning backend
- 615 > rejects open model jobs that omit it with `INVALID_ARGUMENT: The output_uri
- 616 > field is required for this model.` Treat the SDK's "optional" signature as
- 617 > wrong here and always pass a GCS destination.
+ 660 so it is visible in the command string you present for approval. If job
+ 661 submission fails (e.g., due to a missing or invalid parameter), report the error
+ 662 verbatim and present a fresh confirmation prompt showing the updated command
+ 663 before resubmitting.
+ 664 
+ 665 #### Distillation
+ 666 
+ 667 Add `--method DISTILLATION` and `--teacher_model`. `--base_model` is the

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
+ 20 
+ 21 ## Attribution
+ 22 
+ 23 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
+ 24 read [Usage Attribution](references/attribution.md). For commands executed
+ 25 directly in the terminal (never in generated scripts, Terraform, or user code),
+ 26 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
+ 27 attribution suffix to `User-Agent` headers:
+ 28 
+ 29 ```text
+ 30 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-tuning-management)"
+ 31 User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-tuning-management)
+ 32 ```
- 101 > Python snippet fails with an error (such as `403 Permission Denied`, `404 Not
- 102 > Found`, `INVALID_ARGUMENT`, or indicating a dummy/missing project or job ID),
- 103 > you **MUST** inform the user that the project or tuning job does not exist or
- 104 > cannot be accessed. You **MUST** prompt the user to provide a valid Project ID
- 105 > or Job ID, and stop tool execution immediately to wait for their response. Do
- 106 > **NOT** retry or loop, do **NOT** assume the resource is valid, and do **NOT**
- 107 > execute further scripts before receiving valid details from the user.
+ 114 > Python snippet fails because of an invalid filter (e.g., `400 Provided filter
+ 115 > is not valid`), fix or drop the `filter` parameter and re-run. If it fails
+ 116 > with an error indicating a missing or inaccessible project or job ID (`403
+ 117 > Permission Denied`, `404 Not Found`, or invalid resource ID), you **MUST**
+ 118 > inform the user that the project or tuning job does not exist or cannot be
+ 119 > accessed, prompt the user to provide a valid Project ID or Job ID, and stop
+ 120 > tool execution immediately to wait for their response (do **NOT** loop or
+ 121 > assume the resource is valid).
- 112 specific job ID:
+ 126 specific job ID, always execute Python code via `run_command` (do NOT use
+ 127 `curl`). If the user gave a project ID or number, use that **exact** value
+ 128 (otherwise fall back to the configured project). Pass `page_size=20` and read
+ 129 the first page (only page through every job if the user explicitly asks for a
+ 130 total count or the full list). Filter server-side when asked for running jobs
+ 131 (`state="JOB_STATE_RUNNING" OR state="JOB_STATE_PENDING"`) or a specific model
+ 132 display name (`display_name:"NAME"`), print `job.tuned_model_display_name`, and
+ 133 note when `first_page.next_page_token` is set so the 20 most recently updated
+ 134 jobs are not presented as the entire history:
- 117 project_id = "YOUR_PROJECT_ID"
+ 139 project_id = "YOUR_PROJECT_ID"  # If the user gave a project ID/number, use it explicitly
- 125 jobs = client.list_tuning_jobs(parent=parent)
- 126 for job in jobs:
+ 147 request = {
+ 148     "parent": parent,
+ 149     "page_size": 20,
+ 150     # Optional server-side filter, e.g.:
+ 151     # "filter": 'state="JOB_STATE_RUNNING" OR state="JOB_STATE_PENDING"',
+ 152 }
+ 153 response = client.list_tuning_jobs(request=request)
+ 154 first_page = next(iter(response.pages), None)
+ 155 for job in (first_page.tuning_jobs if first_page else []):
+ 157     print(f"Display Name: {job.tuned_model_display_name}")
- 129     print(f"State: {job.state}")
- 130 ```
- 131 
- 132 `list_tuning_jobs` takes no `page_size` keyword. To set one, pass the request:
- 133 `client.list_tuning_jobs(request={"parent": parent, "page_size": 50})`.
+ 159     print(f"State: {job.state.name}")
+ 160 [credential-like text hidden]
+ 161     print("Note: More jobs exist beyond this first page of 20 most recently updated jobs.")
+ 162 ```
- 137 If the user provides a Tuning Job ID and asks for its status:
+ 166 If the user provides a Tuning Job ID and asks for its status, always execute
+ 167 Python code via `run_command` (never use `curl`). If the user gave a project ID
+ 168 or number, use it explicitly:
- 142 project_id = "YOUR_PROJECT_ID"
+ 173 project_id = "YOUR_PROJECT_ID"  # If the user gave a project ID/number, use it explicitly
- 154 print(f"State: {job.state}")
+ 185 print(f"State: {job.state.name}")
- 160 If the user explicitly requests to stop, abort, or cancel a running tuning job:
- 161 
- 162 **Safety Check**: **Action requires explicit typed confirmation before
- 163 proceeding.** You MUST present a dry-run confirmation card listing the Target
- 164 Resource, Command/Script, and Expected Effect, and ask the user to type "I
- 165 confirm" or "Yes, cancel it". Even if the user provided confirming language
- 166 pre-emptively or is providing a corrected/new job ID, you MUST present the
- 167 preview card for that specific job ID and wait for their explicit approval in a
- 168 new turn.
- 169 
- 170 > [!IMPORTANT]
- 171 >
- 172 > **NEVER pre-emptively execute any cancellation code or command before
- 173 > receiving the user's response in a new turn.** You must never speculate or
- 174 > assume that confirmation will be given. Executing cancellation in the same
- 175 > turn as presenting the preview card is a severe safety violation.
+ 191 If the user explicitly requests to stop, abort, or cancel a tuning job:
+ 192 
+ 193 **Safety Check**: Follow the **Tier D (Destructive / Irreversible)**
+ 194 confirmation rules in the Operation Tiers section above:
+ 195 
+ 196 -   **Never report an outcome you did not observe**: Never claim a job was
+ 197     canceled or report a backend error without actually observing it from an API
+ 198     call.
+ 199 -   Present the confirmation preview with **Expected Effect** conditioned on the
+ 200     job's observed state (for active `PENDING`/`RUNNING` jobs: stops in-progress
+ 201     training, which cannot be resumed, without deleting the base model or
+ 202     dataset; if the job is already in a terminal state `SUCCEEDED`, `FAILED`, or
+ 203     `CANCELLED`, state its current terminal state explicitly and note that no
+ 204     active training is running).
+ 205 -   Wait for explicit user confirmation in a new turn before calling
+ 206     `client.cancel_tuning_job(name=name)` via Python (`run_command`), and report
+ 207     the actual API response verbatim.
- 180 project_id = "YOUR_PROJECT_ID"
+ 212 project_id = "YOUR_PROJECT_ID"  # Use the EXACT project ID/number the user gave

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 13   version: "1.0.0"
+ 13   version: "1.0.1"

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.1"
+ 4   version: "1.0.2"
- 47      blocks deployment. In Google Cloud Assured Workloads v2, **Monitor Mode
- 48      deploys detective controls without mutating existing Organization
- 49      Policies**, allowing continuous observability without halting Day 0
- 50      rollout. You MUST NOT confuse these paradigms.
- 51 2. **Authoritative Google Cloud API Contracts & Scope Grounding**:
- 52    * All API assumptions MUST be grounded in published Google Cloud API contracts:
- 53      - **Assured Workloads v1 GA API** (`assuredworkloads.googleapis.com/v1`): Greenfield-only. Contract only creates a brand-new folder (`resourceType: CONSUMER_FOLDER`). It CANNOT adopt or bind to existing brownfield folders (`folders/...`) or projects in-place.
- 54      - **Assured Workloads v2 API** (`assuredworkloads.googleapis.com/v2`): Brownfield-native. Contract binds directly to existing resource hierarchies (`existingFolder`, `existingProject`) and supports non-mutating Monitor Mode (`enforcementMode: DETECTIVE`).
+ 47      blocks deployment. In Google Cloud Assured Workloads, deploying in
+ 48      **Monitoring (`Detective`) mode** enables detective controls without
+ 49      mutating existing Organization Policies, allowing continuous observability
+ 50      without halting Day 0 rollout. You MUST NOT confuse these paradigms.
+ 51 2. **Authoritative Assured Workloads Scope & Deployment Grounding**:
+ 52    * Assured Workloads binds compliance frameworks directly to existing or new
+ 53      Google Cloud folders (`folders/...`) and projects (`projects/...`).
+ 54    * **Existing Workloads (Folders or Projects)**: Recommend deploying in
+ 55      **Monitoring (`Detective`) mode** first to assess and remediate findings
+ 56      safely without mutating existing Organization Policies, and then
+ 57      transitioning to **Preventive** mode.
+ 58    * **New Workloads (Folders or Projects)**: Recommend starting in
+ 59      **Preventive** mode or **Monitoring (`Detective`) mode**.
+ 60    * **Google Cloud Console Deployment**: Always guide the user to deploy the
+ 61      recommended framework via the **Assured Workloads Frameworks tab in Google
+ 62      Cloud Console**
+ 63      (`https://console.cloud.google.com/compliance/configure/frameworks?organizationId=ORGANIZATION_ID`).
+ 64      Do NOT recommend `gcloud assured workloads create` (which only provisions
+ 65      new greenfield folders using legacy regime enums and cannot bind frameworks
+ 66      to existing folders or projects).
- 82    * **Personnel Support Model**: A framework requires a **Paid
- 83      Sovereign/Regulated Support Subscription** when
- 84      `builtin-restrict-technical-support-services` is present in its
- 85      `cloudControlDetails` (as reflected in its `displayName` and
- 86      `description`). Frameworks without
- 87      `builtin-restrict-technical-support-services` (e.g.,
- 88      `builtin-us-data-boundary`, `builtin-eu-data-boundary`) use **Standard
- 89      Commercial Support** ($0 support uplift).
+ 94    * **Personnel Support Model**: Determine whether a framework requires a
+ 95      **Paid Sovereign/Regulated Support Subscription** or uses **Standard
+ 96      Commercial Support** ($0 support uplift) from the framework's public
+ 97      `displayName` and `description` in `frameworks.json`:
+ 98      - **Paid Sovereign/Regulated Support Subscription**: Frameworks whose
+ 99        `description` specifies support personnel access controls (e.g.,
+ 100        `"Support access controls are set to ..."`, `-and-support` variants
+ 101        such as `builtin-eu-data-boundary-and-support` and
+ 102        `builtin-us-data-boundary-and-support`, or regulated standards such as
+ 103        `builtin-il4`, `builtin-il5`, `builtin-itar`, `builtin-fedramp-high`,
+ 104        `builtin-cjis`).
+ 105      - **Standard Commercial Support ($0 support uplift)**: Regional-only Data
+ 106        Boundary frameworks whose `description` sets data location controls only
+ 107        without a support access controls clause (e.g.,
+ 108        `builtin-us-data-boundary`, `builtin-eu-data-boundary`,
+ 109        `builtin-uk-data-boundary`, `builtin-japan-data-boundary`).
+ 110      - **Important**: Do NOT use the mere presence of
+ 111        `builtin-restrict-technical-support-services` in `cloudControlDetails`
+ 112        as a discriminator, because both regional-only and paid-support Data
+ 113        Boundary frameworks include that control.
- 96    * You MUST execute `scripts/evaluate_control_rules.py` with `--frameworks-file=frameworks.json` and `scripts/validate_workload_payload.py` with `--frameworks-file=frameworks.json`.
+ 120    * You MUST execute `scripts/evaluate_control_rules.py` with `--frameworks-file=frameworks.json`.
- 114    * Consult official region availability documentation: [Google Cloud Locations](https://cloud.google.com/about/locations). Note that preview models or APIs are often restricted to `global` or `us-central1`.
+ 138    * Consult official region availability documentation: [Google Cloud Locations](https://cloud.google.com/about/locations).
- 228      `frameworks.json` and reuse it for all candidate evaluations, payload
- 229      validations, and follow-up questions.
+ 252      `frameworks.json` and reuse it for all candidate evaluations and follow-up
+ 253      questions.
- 264        `builtin-uk-gdpr`) to `evaluate_control_rules.py` or
- 265        `validate_workload_payload.py`. Explicitly state that the requested
- 266        standard is not a standalone Assured Workloads Data Boundary framework,
- 267        explain the catalog scope boundary (Data Boundary enforces regional data
- 268        residency, SUR, CMEK, and sovereign support routing rather than legal
- 269        privacy or third-party certification audits), and offer the closest
- 270        adjacent `ASSURED_WORKLOADS` frameworks from `frameworks.json` that match
- 271        their active regional footprint (e.g., `builtin-il5` or
- 272        `builtin-fedramp-high` for US defense/CUI workloads, or
+ 288        `builtin-uk-gdpr`) to `evaluate_control_rules.py`. Explicitly state that
+ 289        the requested standard is not a standalone Assured Workloads Data
+ 290        Boundary framework, explain the catalog scope boundary (Data Boundary
+ 291        enforces regional data residency, SUR, CMEK, and sovereign support
+ 292        routing rather than legal privacy or third-party certification audits),
+ 293        and offer the closest adjacent `ASSURED_WORKLOADS` frameworks from
+ 294        `frameworks.json` that match their active regional footprint (e.g.,
+ 295        `builtin-il5` or `builtin-fedramp-high` for US defense/CUI workloads, or
- 322 4. **Validate Turnkey Assured Workloads Payload**:
- 323    ```bash
- 324    python3 scripts/validate_workload_payload.py \
- 325      --payload-json='{"displayName":"Sovereign-Workload-Enclave","resourceConfig":{"existingFolder":"folders/FOLDER_ID"},"framework":{"framework":"organizations/ORGANIZATION_ID/locations/global/frameworks/FRAMEWORK_ID"}}' \
- 326      --org-id=ORGANIZATION_ID \
- 327      --frameworks-file=frameworks.json
- 328    ```
- 342 * **Value & Safety Invariant**: In-place brownfield adoption via Assured Workloads v2 in **Monitor Mode** (`enforcementMode: DETECTIVE`).
- 343   * **Zero Production Outage Risk**: Mutates zero Organization Policies on Day 0.
+ 358 * **Recommended Deployment Mode**:
+ 359   * **Existing Workloads (Folders or Projects)**: Deploy in **Monitoring (`Detective`) mode** first, then transition to **Preventive** mode after remediating findings.
+ 360   * **New Workloads (Folders or Projects)**: Start in **Preventive** mode or **Monitoring (`Detective`) mode**.
+ 361   * **Zero Production Outage Risk**: Monitoring (`Detective`) mode mutates zero Organization Policies on Day 0.
- 345   * **No Migration Required**: Protects existing resources in-place without provisioning separate folders.
+ 363   * **No Migration Required**: Protects existing folders and projects in-place without migrating resources.
- 352 3. **Non-Disruptive Posture Hardening**: Enrolling in Monitor Mode provides server-side CES posture evaluation while allowing your team to triage Org Policy readiness safely.
+ 370 3. **Non-Disruptive Posture Hardening**: Enrolling existing workloads in Monitoring (`Detective`) mode provides server-side CES posture evaluation while allowing your team to triage Org Policy readiness safely before moving to Preventive mode.
- 368 ### Pre-Flight Org Policy Readiness Recommendations (Prior to Enforced Mode)
- 369 *Pre-flight drift indicators do NOT block Day 0 deployment in Monitor Mode. Address these prior to enabling preventive policy enforcement (authoritative CES and REST control evaluations run server-side after deployment):*
+ 386 ### Pre-Flight Org Policy Readiness Recommendations (Prior to Preventive Mode)
+ 387 *Pre-flight drift indicators do NOT block Day 0 deployment in Monitoring (`Detective`) mode. Address these prior to enabling Preventive policy enforcement (authoritative CES and REST control evaluations run server-side after deployment):*
- 377 ### Deploy via Google Cloud Console (Recommended)
- 378 Review and deploy the recommended framework directly in the Google Cloud Console:
- 379 👉 **[Open Assured Workloads Console](https://console.cloud.google.com/compliance/assuredworkloads?organizationId=ORGANIZATION_ID)**
- 380 *(The Console deployment wizard binds composing controls in Monitor Mode with zero infrastructure mutations).*
+ 395 ### Deploy via Google Cloud Console — Assured Workloads Frameworks Tab (Recommended)
+ 396 Review and deploy the recommended framework directly in the Google Cloud Console **Assured Workloads -> Frameworks** tab:
+ 397 👉 **[Open Assured Workloads Frameworks Console](https://console.cloud.google.com/compliance/configure/frameworks?organizationId=ORGANIZATION_ID)**
+ 398 * **Existing Workloads (Folders or Projects)**: Deploy in **Monitoring (`Detective`) mode** to evaluate posture and remediate findings with zero Day 0 Organization Policy mutations, then transition to **Preventive** mode.
+ 399 * **New Workloads (Folders or Projects)**: Start directly in **Preventive** mode or in **Monitoring (`Detective`) mode**.
- 383 * Assured Workloads compliance regimes may carry support routing or licensing entitlements depending on whether `builtin-restrict-technical-support-services` is bound (standard commercial support vs. paid sovereign/regulated support).
+ 402 * Assured Workloads compliance regimes may carry support routing or licensing entitlements depending on whether the framework enforces regional data location controls only (standard commercial support, $0 support uplift) or specifies support personnel access controls in its `displayName` and `description` (paid sovereign/regulated support).

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Local scripts

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 5   version: "1.0.0"
+ 5   version: "1.0.1"
- 169 | Risk Level        | Impact Category        | Criteria and Recommended Action |
- 170 | ----------------- | ---------------------- | ------------------------------- |
- 171 | 🔴 **High Risk**   | **Breaking Change**    | Immediate risk of blocking      |
- 172 :                   :                        : legitimate production traffic   :
- 173 :                   :                        : upon cutover. Example\:         :
- 174 :                   :                        : `methodenforcement-v422-stable` :
- 175 :                   :                        : only permits `GET`, `HEAD`,     :
- 176 :                   :                        : `POST`, `OPTIONS`, and **blocks :
- 177 :                   :                        : `PUT`, `PATCH`, `DELETE`**      :
- 178 :                   :                        : requests. Requires customer     :
- 179 :                   :                        : confirmation and API            :
- 180 :                   :                        : path/signature exemptions.      :
- 181 | 🟡 **Medium Risk** | **Attention Required** | Behavioral shifts that should   |
- 182 :                   :                        : be validated in Preview Mode    :
- 183 :                   :                        : before enforcement\:<br>•       :
- 184 :                   :                        : **Coverage Expansion**\:        :
- 185 :                   :                        : Sensitivity level 4 activates   :
- 186 :                   :                        : significantly more signatures   :
- 187 :                   :                        : (for example, RCE expands from  :
- 188 :                   :                        : 11/15 to 44 signatures; SQLi    :
- 189 :                   :                        : expands to 60 signatures).<br>• :
- 190 :                   :                        : **Deprecated Exemption Lost**\: :
- 191 :                   :                        : Legacy rule opted out of any of :
- 192 :                   :                        : the 15 retired CRS 3.0/3.3 IDs  :
- 193 :                   :                        : (`981172`, `981173`, `980130`,  :
- 194 :                   :                        : `949110`; SQLi\: `942110`;      :
- 195 :                   :                        : RCE\: `932100`, `932105`,       :
- 196 :                   :                        : `932106`, `932110`, `932115`,   :
- 197 :                   :                        : `932150`; Scanner Detection\:   :
- 198 :                   :                        : `913101`, `913102`, `913110`,   :
- 199 :                   :                        : `913120`), which are omitted in :
- 200 :                   :                        : 4.22.<br>• **Custom Filter      :
- 201 :                   :                        : Continuity**\: Preserved custom :
- 202 :                   :                        : header/cookie/query/IP          :
- 203 :                   :                        : conditions combined with WAF    :
- 204 :                   :                        : calls.                          :
- 205 | 🟢 **Low Risk**    | **Clean Upgrade**      | Direct 1:1 ruleset translation  |
- 206 :                   :                        : with preserved active opt-outs  :
- 207 :                   :                        : and no expected behavioral      :
- 208 :                   :                        : divergence (for example,        :
- 209 :                   :                        : standard SQLi or XSS rules).    :
- 210 | ⚪ **No Action**   | **Pass-Through**       | Non-OWASP rules (pure IP        |
- 211 :                   :                        : allowlist/denylist, rate        :
- 212 :                   :                        : limiting, default rule).        :
- 213 :                   :                        : Carried over unchanged.         :
+ 169 <!-- mdformat off -->
+ 170 
+ 171 | Risk Level | Impact Category | Criteria and Recommended Action |
+ 172 | :--- | :--- | :--- |
+ 173 | 🔴 **High Risk** | **Breaking Change** | Immediate risk of blocking legitimate production traffic upon cutover. Example: `methodenforcement-v422-stable` only permits `GET`, `HEAD`, `POST`, `OPTIONS`, and **blocks `PUT`, `PATCH`, `DELETE`** requests. Requires customer confirmation and API path/signature exemptions. |
+ 174 | 🟡 **Medium Risk** | **Attention Required** | Behavioral shifts that should be validated in Preview Mode before enforcement:<br>• **Coverage Expansion**: Sensitivity level 4 activates significantly more signatures (for example, RCE expands from 11/15 to 44 signatures; SQLi expands to 60 signatures).<br>• **Deprecated Exemption Lost**: Legacy rule opted out of any of the 15 retired CRS 3.0/3.3 IDs (`981172`, `981173`, `980130`, `949110`; SQLi: `942110`; RCE: `932100`, `932105`, `932106`, `932110`, `932115`, `932150`; Scanner Detection: `913101`, `913102`, `913110`, `913120`), which are omitted in 4.22.<br>• **Custom Filter Continuity**: Preserved custom header/cookie/query/IP conditions combined with WAF calls. |
+ 175 | 🟢 **Low Risk** | **Clean Upgrade** | Direct 1:1 ruleset translation with preserved active opt-outs and no expected behavioral divergence (for example, standard SQLi or XSS rules). |
+ 176 | ⚪ **No Action** | **Pass-Through** | Non-OWASP rules (pure IP allowlist/denylist, rate limiting, default rule). Carried over unchanged. |
+ 177 
+ 178 <!-- mdformat on -->

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

- 4   version: "1.0.2"
+ 4   version: "1.0.3"
- 15 allowed-tools:
- 16   - terraform
- 17   - gcloud
+ 15 allowed-tools: terraform gcloud

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 4   version: "1.1.2"
+ 4   version: "1.1.3"
- 140 - **Scalar & Stringified JSON Extraction**: Use `JSON_VALUE(json_col, '$.path')` for native `JSON` columns (omit dots before array indexes, e.g., `$.items[1]`), and `CAST(JSON_EXTRACT_SCALAR(SAFE.PARSE_JSON(CAST(source.col AS STRING)), '$.path') AS TYPE)` for stringified JSON columns. Wrap typed extractions in `SAFE_CAST(... AS INT64|BOOL|TIMESTAMP|NUMERIC)` when strict typing is required.
+ 140 - **Scalar & Stringified JSON Extraction**: Use `JSON_VALUE(json_col, '$.path')`
+ 141   for native `JSON` columns (omit dots before array indexes, e.g.,
+ 142   `$.items[1]`), and
+ 143   `CAST(JSON_EXTRACT_SCALAR(SAFE.PARSE_JSON(CAST(source.col AS STRING)), '$.path') AS TYPE)`
+ 144   for stringified JSON columns. Preserve 1:1 warehouse cast semantics: wrap
+ 145   typed extractions in `CAST(... AS INT64|BOOL|TIMESTAMP|NUMERIC)` for Snowflake
+ 146   `CAST` / `::TYPE` / `TO_*` (failing fast on invalid data), and use
+ 147   `SAFE_CAST(...)` only when the Snowflake source explicitly uses `TRY_CAST` or
+ 148   `TRY_TO_*` (returning `NULL` on malformed values).
- 147 - **Comparisons**: Always use `SAFE_CAST` on both sides of a join or filter if types are not identical. Use `AS STRING` for universal comparison safety if necessary.
+ 155 - **Comparisons**: Use `CAST` on both sides of a join or filter when types are
+ 156   not identical (using `AS STRING` for universal comparison safety if
+ 157   necessary). Preserve 1:1 cast parity with Snowflake (`CAST` / `::TYPE` to
+ 158   `CAST`, and `TRY_CAST` / `TRY_TO_*` to `SAFE_CAST`); do not introduce
+ 159   `SAFE_CAST` for standard Snowflake casts because silently coercing malformed
+ 160   keys to `NULL` changes warehouse behavior and masks join or primary-key
+ 161   errors.
- 150     - For placeholder columns, always use explicit type casting: `SAFE_CAST(NULL AS TYPE)`.
+ 164     - For placeholder columns, always use explicit type casting: `CAST(NULL AS TYPE)`.
- 155 - **Date Add**: Use `DATE_ADD(SAFE_CAST(col AS DATETIME), INTERVAL num HOUR)`.
+ 169 - **Date Add**: Use `DATE_ADD(CAST(col AS DATETIME), INTERVAL num HOUR)`.

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 56 | Generation | [references/generation.md](references/generation.md) | `Generate`, `GenerateText`, `GenerateData`, streaming, output formats |
+ 56 | Generation | [references/generation.md](references/generation.md) | `Generate`, `GenerateText`, `GenerateData`, streaming, output formats, `Embed` |

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 198 -   [Examples](references/examples.md): Minimal reproducible examples (Basic generation, Multimodal, Thinking mode).
+ 198 -   [Examples](references/examples.md): Minimal reproducible examples (Basic generation, Multimodal, Thinking mode, Embeddings).

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 5   managed Prometheus. Use when configuring GKE monitoring, setting up GKE logging,
- 6   or configuring Prometheus metrics collection, and to troubleshoot Managed
- 7   Service for Prometheus (GMP) issues such as missing metrics, unhealthy scrape
- 8   targets, PodMonitoring misconfiguration, rule/alert evaluation failures, and
- 9   monitoring permission errors. Don't use to configure local application logging
- 10   frameworks or external APMs outside GKE.
+ 5   managed Prometheus. Use when configuring GKE monitoring, setting up GKE
+ 6   logging, or configuring Prometheus metrics collection, to diagnose GKE control
+ 7   plane, API server, admission webhook, etcd storage, node registration or
+ 8   label, and pod eviction, preemption, or scheduling issues using GKE metrics,
+ 9   Kubernetes events, and Cloud Logging, and to troubleshoot Managed Service for
+ 10   Prometheus (GMP) issues such as missing metrics, unhealthy scrape targets,
+ 11   PodMonitoring misconfiguration, rule/alert evaluation failures, and monitoring
+ 12   permission errors. Don't use to configure local application logging frameworks
+ 13   or external APMs outside GKE.
- 12   version: "1.1.7"
+ 15   version: "1.2.1"
- 18 This reference covers monitoring, logging, and metrics configuration for GKE.
- 19 The golden path enables comprehensive observability including control-plane
- 20 metrics.
+ 21 This reference covers monitoring, logging, and metrics configuration and
+ 22 troubleshooting for Google Kubernetes Engine (GKE). The golden path enables
+ 23 comprehensive observability including control-plane metrics and Managed Service
+ 24 for Prometheus (GMP).
- 26 ## Attribution
- 27 
- 28 **MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you
- 29 MUST read [Usage Attribution](references/attribution.md). For commands executed
- 30 directly in the terminal (never in generated scripts, Terraform, or user code),
- 31 prefix `gcloud` with
- 32 `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-observability)"`
- 33 and append `agent-skills/1.0 (skill:gke-observability)` to `User-Agent` headers.
+ 30 ## Usage Attribution
+ 31 
+ 32 Do not run live `kubectl`, `gcloud`, or `curl` commands unless the user names a
+ 33 target cluster/project or asks to inspect a live cluster (output commands and
+ 34 queries with placeholders, and skip [Usage Attribution](references/attribution.md)).
+ 35 Before running any live command, read [Usage Attribution](references/attribution.md),
+ 36 prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-observability)"`,
+ 37 and append `agent-skills/1.0 (skill:gke-observability)` to `User-Agent` headers
+ 38 (never in generated scripts, Terraform, or user-facing code).
+ 39 
+ 40 ## Sub-Skill Reference Routing (Progressive Disclosure)
+ 41 
+ 42 > **Complete Reference Index** (no `scripts/` directory or unlisted reference
+ 43 > files exist — do not run `ls` on the skill folder; read only the matching
+ 44 > reference below when answering deep diagnostic, metric, log, or GMP questions):
+ 45 
+ 46 1.  **[Control-Plane Metrics, Storage, Webhooks & Capacity](references/control-plane-metrics-and-storage.md)**:
+ 47     Read for GKE control-plane (KCP) VM CPU or RAM/memory usage questions (not
+ 48     publicly exposed) and customer-visible alternatives; cluster etcd /
+ 49     etcd-compatible storage left, quota & per-resource scalability limits;
+ 50     admission webhook latency, system namespace/Lease/upgrade exclusions,
+ 51     `APIService` discovery bloat, client discovery caching bursts
+ 52     (`/apis/custom.metrics.k8s.io`, `/apis/metrics.k8s.io`) & proactive GKE
+ 53     Recommender insights; watch storms; controller-manager workqueue & scheduler
+ 54     lag; or control-plane headroom, VM autoscaling & node-count pre-scaling,
+ 55     network egress, connections (`65k`, no per-replica metric) & Protobuf.
+ 56 2.  **[Cloud Logging, Audit Attribution, APF & API Server Traces](references/logging-audit-and-apiserver-traces.md)**:
+ 57     Read for `kube-apiserver` slow-request `Trace[` logs (`trace.go` & KEP-647);
+ 58     `httplog.go` client load (`user_agent`, `verb`, `apf_iseats`); Cloud Audit
+ 59     Log noisy-neighbor, heavy `LIST` & unindexed CRD `fieldSelector` scan
+ 60     tail-latency attribution; API Priority and Fairness (APF) `429`/`504`/`404`
+ 61     throttling; `409 Conflict` hot objects (`ConfigMap` -> `Lease` heartbeats) &
+ 62     `RenewDeadline / 2` leader-election timeouts; `pods/exec` saturation,
+ 63     Konnectivity (`No agent available`), disabled Cloud KMS keys, or in-cluster
+ 64     GCP IAM OAuth token webhook authorizer saturation.
+ 65 3.  **[Cluster/Node/Pod Health, Maintenance & Managed Prometheus (GMP)](references/cluster-node-pod-health-and-gmp.md)**:
+ 66     Read for control-plane availability (`kubernetes.io/cluster/kcp_healthchecks`
+ 67     rate ratio & ruling out KCP outages); maintenance windows
+ 68     (`in_maintenance_window`), zonal resize downtime & cluster access errors
+ 69     (`EOF` / `masterAuthorizedNetworksConfig`); node readiness, registration
+ 70     (`AUTO_REPAIR_NODES`, Private Google Access) & persistent node-pool labels;
+ 71     pod startup timelines, crashing pod logs, `tolerationSeconds: 0` mass
+ 72     eviction & Autopilot preemption; or multi-burn-rate SLO alerting
+ 73     (`GlobalRules`) & GMP / Grafana / `PodMonitoring` manifests & troubleshooting.
- 46 ### Control-Plane Metrics (Golden Path Addition)
- 47 
- 48 The golden path adds three control-plane monitoring components not present in
- 49 default clusters:
- 50 
- 51 | Component            | What It Monitors                                                       |
- 52 | -------------------- | ---------------------------------------------------------------------- |
- 53 | `APISERVER`          | API server request latency, error rates, admission webhook performance |
- 54 | `SCHEDULER`          | Scheduling latency, pending pods, scheduling failures                  |
- 55 | `CONTROLLER_MANAGER` | Controller work queue depth, reconciliation latency                    |
- 56 
- 57 These are critical for diagnosing cluster-level issues (slow API responses,
- 58 scheduling delays, stuck controllers).
- 59 
- 60 When recommending any control-plane metric below, always state that it is a
- 61 Managed Service for Prometheus (GMP) metric that requires explicit enabling
- 62 (`--monitoring=SYSTEM,API_SERVER,...` and `--enable-managed-prometheus`) and
- 63 link to
- 64 https://docs.cloud.google.com/kubernetes-engine/docs/how-to/control-plane-metrics:
- 65 
- 66 -   **API storage utilization by resource
- 67     (`apiserver_resource_size_estimate_bytes`)**: Use
- 68     `apiserver_resource_size_estimate_bytes` (grouped by `group` and `resource`)
- 69     to identify which Kubernetes resource types consume the most API server
- 70     storage bytes in etcd, complementing object counts
- 71     (`apiserver_storage_objects`) and total database size
- 72     (`apiserver_storage_size_bytes`).
- 73 -   **Admission webhook latency, timeouts, and control-plane recommendations
- 74     (`apiserver_admission_webhook_admission_duration_seconds`)**: When API calls
- 75     time out or fail and mutating or validating admission webhooks are
- 76     suspected, query the opt-in GMP metric
- 77     `apiserver_admission_webhook_admission_duration_seconds` (grouped by `name`,
- 78     `type`, `operation`, and `rejected`) to pinpoint slow or failing webhooks;
- 79     also inspect `ValidatingWebhookConfiguration` /
- 80     `MutatingWebhookConfiguration` `timeoutSeconds`, `failurePolicy`,
- 81     `namespaceSelector` exclusions (such as `kube-system`), and backing webhook
- 82     Service/Pod health. Strongly warn users against ignoring GKE control-plane
- 83     recommendations about optimizing admission webhooks or CRDs with an invalid
- 84     `caBundle` because unoptimized webhooks and invalid CRD `caBundle`
- 85     configurations can overload or destabilize the GKE control plane, and always
- 86     link to
- 87     https://docs.cloud.google.com/kubernetes-engine/docs/how-to/optimize-webhooks.md.txt
+ 86 ## Enabling Full Monitoring & Logging
+ 87 

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 496fbede89da

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 6   version: "1.1.2"
+ 6   version: "1.2.0"
- 77 | Capability | Remote MCP Tool (Primary) | Local Tool (Fallback) | Description |
+ 77 <!-- disableFinding(LINE_OVER_80) -->
+ 78 
+ 79 | Capability & Stage | Primary / Fallback Tool | Key Input Arguments | Return Values / Output |
- 79 | **Validate Rule Syntax** | `validate_rule` | `validate_rule` | Validates YARA-L 2.0 syntax before deployment. |
- 80 | **Test / Check Detections** | `list_rule_detections` | `list_rule_detections` | Evaluates rule detections against historical events. |
- 81 | **Inspect Rule Configuration** | `get_rule` | `get_rule` | Fetches rule text, author, version, and alerting status. |
- 82 | **List Environment Rules** | `list_rules` | `list_rules` | Queries active or archived tenant rules. |
- 83 | **Deploy New Rule** | `create_rule` | `create_rule` | Deploys validated YARA-L rule into SecOps. |
- 84 | **Generate TDOs** | `generate_threat_detection_opportunity` | `generate_threat_detection_opportunity` | Extracts TDOs from threat intelligence text. |
- 85 | **Generate Synthetic Events** | `generate_synthetic_events` | `generate_synthetic_events` | Simulates attacker behaviors as UDM events. |
- 86 | **Evaluate Rule Coverage** | `evaluate_rule_coverage_long_running` | `evaluate_rule_coverage` | Tests synthetic events against tenant rule corpus. |
- 87 | **Poll Async Operations** | `get_operation` | `get_operation` | Checks status of long-running coverage evaluation. |
- 88 | **Mitigate Coverage Gaps** | `generate_rules` | `generate_rules` | Codifies YARA-L detection logic for verified gaps. |
+ 81 | **Validate Syntax** (W1.2) | `validate_rule` (`scripts/validate_yaral_rule.py`) | `rule`: YARA-L text (`--input {rule_or_doc_path}`) | Compilation status, errors |
+ 82 | **Test Detections** (W1.3) | `list_rule_detections` | `rule_id` or filters | Historical hits, timestamps |
+ 83 | **Inspect Rule** (W1/W2) | `get_rule` | `rule_id`: Rule ID | Config, YARA-L, `alertingEnabled` |
+ 84 | **List Rules** (W1/W2) | `list_rules` | `page_size`, `page_token` | Active/archived rule summaries |
+ 85 | **Deploy Rule** (W1/W2) | `create_rule` | `rule`: Validated YARA-L | Created rule with `rule_id` |
+ 86 | **Generate TDOs** (W2.2) | `generate_threat_detection_opportunity` | Cleaned CTI text | Threat Detection Opportunities |
+ 87 | **Synthetic Events** (W2.3) | `generate_synthetic_events` | `threatDetectionOpportunity` | `syntheticEvents` (`udmJson`) |
+ 88 | **Evaluate Coverage** (W2.4) | `evaluate_rule_coverage_long_running` (`evaluate_rule_coverage`) | `threatDetectionOpportunityEvents` | `google.longrunning.Operation` |
+ 89 | **Poll Async Ops** (W2.4) | `get_operation` | `name`: Operation name | `done: bool`, `result.response` |
+ 90 | **Mitigate Gaps** (W2.6) | `generate_rules` | Gap TDO objects | Drafted YARA-L 2.0 rules |
- 112     $e.target.process.file.full_path = /certutil\.exe/nocase
+ 114     $e.target.process.file.full_path = /certutil\.exe/ nocase
- 114       $e.target.process.command_line = /-urlcache/nocase or
- 115       $e.target.process.command_line = /-split/nocase
+ 116       $e.target.process.command_line = /-urlcache/ nocase or
+ 117       $e.target.process.command_line = /-split/ nocase
- 117     $e.principal.user.userid = $user
- 118     $e.principal.hostname = $host
+ 119     $user = $e.principal.user.userid
+ 120     $host = $e.principal.hostname
- 139    - Regex matches use `/pattern/nocase` format.
- 140    - Bound event placeholders to match variables (e.g., `$e.principal.user.userid = $user`).
+ 141    - Regex matches use `/pattern/ nocase` or ``re.regex($e.{field}, `pattern`) nocase`` format.
+ 142    - Bind event placeholders on the left-hand side (e.g., `$user = $e.principal.user.userid`).
- 150 Always validate rule syntax before attempting creation or running tests:
- 151 
+ 152 Always validate rule syntax and structural logic before attempting creation or running tests:
+ 153 
+ 154 - Highlight and verify **`match:` sections** (correlation grouping variables and sliding/hop time windows, e.g., `$user, $host over 5m`) and **`condition:` thresholds** (event count or outcome comparison thresholds, e.g., `#e >= 1`, `#proc > 5`, or `$total >= 10`).
+ 155 - Consult [yaral_compiler_and_udm_guardrails.md](references/yaral_compiler_and_udm_guardrails.md) and run `python3 scripts/validate_yaral_rule.py --input {rule_or_doc_path}` as a fast offline pre-check (or fallback when MCP tools are unavailable) to verify canonical section ordering, `match:` windows, `condition:` thresholds, `outcome:` aggregations, external `nocase` placement, and `net.ip_in_range_cidr()` syntax.
- 154   - If syntax errors or invalid UDM field references are reported, correct the syntax and re-validate.
+ 158   - If syntax errors, invalid UDM field references, malformed `match:` windows, or invalid `condition:` threshold expressions are reported, correct the syntax and re-validate.
- 159 Verify rule behavior and detection fidelity against telemetry:
- 160 
- 161 - Call `list_rule_detections` with rule parameters to inspect historical triggers over a lookback window (e.g., last 24 to 72 hours).
- 162 - Assess detection volume:
- 163   - **Zero Detections**: Typical for novel threats. Verify event conditions against expected UDM event structures.
+ 163 Verify rule behavior, `match:` window correlation, `condition:` thresholds, and detection fidelity against historical telemetry or synthetic events (`evaluate_rule_coverage_long_running` / `evaluate_rule_coverage` and `generate_synthetic_events`):
+ 164 
+ 165 - Call `list_rule_detections` with rule parameters to inspect historical triggers over a lookback window (e.g., last 24 to 72 hours), or evaluate synthetic UDM events via `generate_synthetic_events` and `evaluate_rule_coverage_long_running` (`evaluate_rule_coverage`).
+ 166 - Assess detection volume and tune `match:` windows and `condition:` thresholds:
+ 167   - **Zero Detections**: Typical for novel threats. Verify event conditions, `match:` correlation windows, and `condition:` thresholds against expected UDM event structures.
- 165   - **Excessive Detections (> 100)**: Likely noisy or overbroad. Refine filters, exclude benign administrative parent processes, or require multi-event correlation.
+ 169   - **Excessive Detections (> 100)**: Likely noisy or overbroad. Refine filters, adjust `match:` windows or `condition:` thresholds, exclude benign administrative parent processes, or require multi-event correlation.
- 276 - Review generated YARA-L 2.0 rules for clarity, logic correctness, and proper event variables.
+ 280 - Review generated YARA-L 2.0 rules against [yaral_compiler_and_udm_guardrails.md](references/yaral_compiler_and_udm_guardrails.md) and run `python3 scripts/validate_yaral_rule.py --input {rule_or_doc_path}` (alongside `validate_rule`) to confirm section ordering, `outcome:` aggregations, external `nocase`, and UDM field validity before presenting rules for deployment.
- 305 ## Tool Reference Matrix
- 306 
- 307 | Tool Name | Workflow Stage | Input Arguments | Return Values / Output |
- 308 | :--- | :--- | :--- | :--- |
- 309 | `validate_rule` | Workflow 1 (Step 2) | `rule`: YARA-L rule text string | Validation status, compilation errors, syntax warnings |
- 310 | `list_rule_detections` | Workflow 1 (Step 3) | `rule_id` or query parameters | Historical detection list, entity counts, timestamps |
- 311 | `get_rule` | Both Workflows | `rule_id`: Rule identifier string | Rule configuration, YARA-L text, author, alerting status |
- 312 | `list_rules` | Both Workflows | `page_size`, `page_token`, filter expressions | Array of tenant rule summaries |
- 313 | `create_rule` | Both Workflows | `rule`: Validated YARA-L rule text | Created rule object with new `rule_id` |
- 314 | `generate_threat_detection_opportunity` | Workflow 2 (Step 2) | Cleaned CTI text | Array of Threat Detection Opportunity (TDO) objects |
- 315 | `generate_synthetic_events` | Workflow 2 (Step 3) | `threatDetectionOpportunity`: TDO object | `syntheticEvents` containing `rawLog`, `udm`, and `udmJson` |
- 316 | `evaluate_rule_coverage_long_running` | Workflow 2 (Step 4) | `threatDetectionOpportunityEvents`: `[{threatDetectionOpportunityId, udmsJson}]` | `google.longrunning.Operation` with operation `name` |
- 317 | `get_operation` | Workflow 2 (Step 4) | `name`: Operation resource name | Operation state (`done: bool`, `result.response`) |
- 318 | `generate_rules` | Workflow 2 (Step 6) | TDO objects for verified gaps | Array of newly drafted YARA-L 2.0 detection rules |
+ 309 ## YARA-L 2.0 Compiler Guardrails & Local Validation
+ 310 
+ 311 Before calling `validate_rule` or `create_rule`, verify rules against these resources:
+ 312 
+ 313 - **Compiler & UDM Schema Reference**: Read [yaral_compiler_and_udm_guardrails.md](references/yaral_compiler_and_udm_guardrails.md) for `match:` outcome aggregation rules, repeated-field `array_distinct()`, backtick regexes with external `nocase`, `strings.coalesce()` type homogeneity, `ENTITY_CONTEXT` namespace joins, composite detections, and log-source parser guardrails (`GCP_CLOUDAUDIT`, `KUBERNETES_AUDIT`, `WINEVTLOG`, `LINUX_SYSMON`, `GCP_DNS`, `GCP_FIREWALL`, `PFSENSE`).
+ 314 - **Offline Structural Validator**: Run [validate_yaral_rule.py](scripts/validate_yaral_rule.py) (`python3 scripts/validate_yaral_rule.py --input {rule_or_doc_path}`) to check section order, `match:` windows, `outcome:` aggregations, external `nocase`, and `net.ip_in_range_cidr()` prior to remote compilation.
+ 315 

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Network or broad shell

81b0e8f8f405 → 496fbede89da

- 6   version: "1.1.2"
+ 6   version: "1.2.0"
- 38    - **SOAR Case Operations**: `get_case` (with expand parameters), `list_cases`, `list_case_alerts`, `create_case_comment`, `update_case`, `execute_bulk_close_case`
+ 38    - **SOAR Case & Alert Operations**: `get_case` (with expand parameters),
+ 39      `list_cases`, `list_case_alerts`, `get_case_alert`, `get_security_alert`,
+ 40      `create_case_comment`, `update_case`, `execute_bulk_close_case`
- 42    - **SOAR Case Operations**: `get_case_full_details`, `list_cases`, `post_case_comment`, `change_case_priority`
+ 44    - **SOAR Case & Alert Operations**: `get_case_full_details`, `list_cases`, `get_security_alert`, `post_case_comment`, `change_case_priority`
- 88      - Remote: `get_case` (expand='tasks,tags,products') and `list_case_alerts`
- 89      - Local: `get_case_full_details`
+ 90      - Remote: `get_case` (expand='tasks,tags,products'), `list_case_alerts`, `get_case_alert`, and `get_security_alert`
+ 91      - Local: `get_case_full_details` and `get_security_alert`
- 122        AND target.process.file.full_path = /(\\(powershell|pwsh|cmd|wscript|cscript)\.exe|\/(ba|z|da)?sh)$/nocase
+ 124        AND target.process.file.full_path = /(\\(powershell|pwsh|cmd|wscript|cscript)\.exe|\/(ba|z|da)?sh)$/ nocase
+ 133 
+ 134 4. **Assess Involved Entities & Threat Intelligence (Always Required)**:
+ 135    - Before dispositioning any alert (including phishing, credential, endpoint,
+ 136      or network alerts), always enrich every involved entity (`${KEY_ENTITIES}`:
+ 137      sender/recipient users, hosts, source/destination IPs, domains, URLs, and
+ 138      file hashes) using `summarize_entity` (or `lookup_entity`) to assess entity
+ 139      context and asset criticality, and query `get_ioc_match` (or
+ 140      `get_ioc_matches`) to check for active threat intelligence and IoC matches
+ 141      (see Section 2).
+ 267 
+ 268 ---
+ 269 
+ 270 <!-- disableFinding(LINE_OVER_80) -->
+ 271 
+ 272 ## UDM Log-Source Triage References
+ 273 
+ 274 Load the domain-specific reference module matching the alert's `metadata.log_type` or attack surface for parser quirk workarounds, field-coalescing patterns, and UDM triage selectors:
+ 275 
+ 276 | Log Source / Domain | Reference Module | Key Triage Coverage |
+ 277 | :--- | :--- | :--- |
+ 278 | **Keycloak & SSO Identity** | [01_keycloak_identity.md](references/01_keycloak_identity.md) | `KEYCLOAK` username/error coalescing, OAuth2 code replay, admin mutations, DB failover storms |
+ 279 | **GCP IAM, Keys & Compute** | [02_gcp_iam_compute_and_keys.md](references/02_gcp_iam_compute_and_keys.md) | `GCP_CLOUDAUDIT` gRPC `7`/`16` vs operational `BLOCK`, `GCPPEAS`, GCE disk attach & IAP LRO dedup, SCC `IP_FORWARDING_ENABLED` |
+ 280 | **Kubernetes & Containers** | [03_kubernetes_and_containers.md](references/03_kubernetes_and_containers.md) | `KUBERNETES_AUDIT` `/exec`, `/portforward` host correlation, `/binding` naked pods, Artifact Registry, `CloudFox` |
+ 281 | **Endpoints, AuditD & Linux Containers** | [04_endpoint_auditd_vss_and_linux_containers.md](references/04_endpoint_auditd_vss_and_linux_containers.md) | Cloud VSS disk cloning, `AUDITD` hex `proctitle` & `auid`, `LINUX_SYSMON` `masscan` raw-socket bypass, `WINDOWS_DEFENDER_AV`, `OSQUERY_EDR`, K3s/RKE2 UAC forensics |
+ 282 | **Cloud DNS, Firewall, WebRTC & GTI** | [05_network_dns_webrtc_and_gti.md](references/05_network_dns_webrtc_and_gti.md) | WebRTC ICE/STUN port-scan false positives, `GCP_FIREWALL` `0.0.0.0` hairpin & `resource.name`, `GCP_DNS` `GENERIC_EVENT` downgrade, AD SRV `NXDOMAIN`, GTI domain pivots |
+ 283 | **Multi-Tenant MSSP & CMDB** | [06_mssp_and_cmdb_enrichment.md](references/06_mssp_and_cmdb_enrichment.md) | Overlapping RFC 1918 `principal.namespace` disambiguation, `SNIPE_IT` `ENTITY_CONTEXT` joins, Data RBAC, `cases:merge` entity clustering |
+ 284 | **pfSense Firewall & WireGuard** | [07_pfsense_firewall_and_wireguard.md](references/07_pfsense_firewall_and_wireguard.md) | `PFSENSE` split-brain hostnames, WireGuard peer persistence, `filterlog` state-flush DNS reply drops, serial `getty` boot autologin vs `ROOT LOGIN` |
+ 285 | **Hybrid AD-to-Cloud & AA26-237A** | [08_hybrid_ad_cloud_and_cisa_aa26_237a.md](references/08_hybrid_ad_cloud_and_cisa_aa26_237a.md) | OAuth secret injection, AD `4722` reactivation to cloud SSO, MAQ `4741` & ADCS ESC1 `4887`, Windows `4624`/`4625` dual-stream dedup, Seatbelt RE2 boundaries |

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Instructions only → After Instructions only

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Instructions only

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Local scripts → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Local scripts

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

81b0e8f8f405 → 496fbede89da

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 81b0e8f8f405

No earlier version was observed for comparison.

Compare on GitHub