Update skills for Query Insights API and Vitess read-only regions

01-readonly-inventory/SKILL.md

@@ -13,7 +13,8 @@ Build an evidence-backed inventory of a PlanetScale database without making chan
 
 Allowed by default:
 
-- List organizations, databases, branches, keyspaces, regions, and sizes.
+- List organizations, databases, branches, keyspaces, regions, branch sizes,
+  and Vitess read-only region cluster sizes and replica counts.
 - Read branch metadata.
 - Read webhook configuration.
 - Read schema recommendations.
@@ -64,8 +65,12 @@ Verified interface notes (recheck against the docs when a command fails):
   administrative connection. Do not cancel queries or terminate connections
   unless the operator explicitly approves that operational action.
 - Live query telemetry: `.../branches/{branch}/insights`. Anomalies:
-  `.../branches/{branch}/insights/anomalies`. The `query-patterns` path
-  returns generated report metadata, not live patterns.
+  `.../branches/{branch}/insights/anomalies`. The public Query Insights API
+  also exposes query statistics, per-fingerprint statistics and summaries,
+  query errors, anomalies, query tags, tag groupings, and Postgres traffic
+  budgets affecting a query fingerprint. Service tokens need `read_database`
+  permission for these endpoints. The `query-patterns` path returns generated
+  report metadata, not live patterns.
 - Traffic budgets: `.../branches/{branch}/traffic/budgets`. The CLI has no
   `pscale traffic-control budget list`; use the API for inventory.
 - Postgres roles: list via `.../branches/{branch}/roles`; fetch a single
@@ -105,7 +110,8 @@ Record:
 - Region and cloud provider.
 - Production/development branch status.
 - Branch protection and safe workflow state.
-- Size and cluster shape.
+- Size and cluster shape, including Vitess read-only region cluster sizes and
+  replica counts per keyspace when configured.
 
 ### Branches and schema workflow
 

02-vitess-safety-review/SKILL.md

@@ -70,6 +70,20 @@ Recommend a branch topology:
 
 Do not create branches without approval.
 
+### Read-only regions and cluster shape
+
+Check:
+
+- Primary region and production branch size.
+- Read-only regions configured for each keyspace.
+- Cluster size and replica count for each Vitess read-only region.
+- Whether application read traffic, analytics, agents, or regional workloads are
+  expected to use read-only regions.
+
+Recommend documenting the intended read topology before changing it. Read-only
+region cluster size and replica count changes are behavior-changing capacity
+changes requiring approval; do not apply them automatically.
+
 ### Query Insights
 
 Review Insights for:

04-query-insights-and-tags/SKILL.md

@@ -30,12 +30,19 @@ For the selected database and branch, inspect:
   over time. Treat missing or declining relevant-vindex usage as an indexing
   or routing investigation input, not as proof that a new index is required.
 
-The Insights API (`.../branches/{branch}/insights`) returns hourly
-pattern snapshots. Duration aggregates use field names like
-`sum_total_duration_millis` — not `total_time_millis`. When the
-aggregation window is not explicit in the response, time-share
-percentages within the returned window are more reliable than absolute
-duration totals; prefer them for ranking.
+PlanetScale exposes Query Insights data through public API endpoints.
+Use them for the dashboard-backed telemetry surfaces: query statistics,
+per-fingerprint statistics and summaries, query errors, anomalies, query
+tags and tag groupings, and Postgres traffic budgets affecting a query
+fingerprint. Service tokens need `read_database` permission for these
+endpoints. Verify exact paths in the OpenAPI reference before calling.
+
+The branch Insights endpoint (`.../branches/{branch}/insights`) returns
+hourly pattern snapshots. Duration aggregates use field names like
+`sum_total_duration_millis` — not `total_time_millis`. When the aggregation
+window is not explicit in the response, time-share percentages within the
+returned window are more reliable than absolute duration totals; prefer them
+for ranking.
 
 ### Tag coverage
 

05-traffic-control-recommendations/SKILL.md

@@ -17,6 +17,8 @@ Before recommending rules, inspect:
 
 - Current budgets and rules.
 - Insights query patterns.
+- For candidate Postgres fingerprints, any Query Insights API data showing
+  which traffic budgets already affect the fingerprint.
 - Current query tags.
 - Application routes and jobs.
 - Known critical paths.
@@ -157,6 +159,8 @@ For each proposed budget:
 - Proposed tags or fingerprint.
 - Limit rationale.
 - Queries seen in Insights that justify it.
+- Existing budgets already affecting the target fingerprint, if Query Insights
+  exposes that data.
 - Safety risk.
 - Test/observe plan.
 - Rollback plan.

11-change-gates-and-approval-contract/SKILL.md

@@ -58,7 +58,7 @@ Always requires explicit approval:
 - Change backup schedule or retention.
 - Create restore branch.
 - Create backup beyond automatic backups.
-- Change branch size or replica topology.
+- Change branch size, read-only region cluster size, or replica topology.
 - Edit repository files or dependencies.
 
 ### Class D: production data/availability impacting

12-best-practices-matrix/SKILL.md

@@ -16,6 +16,10 @@ Map database findings to recommended PlanetScale features. Use this to ensure th
 Recommend for every production database:
 
 - Review slow, expensive, high-frequency, and erroring query patterns.
+- Use public Query Insights API endpoints when automation needs dashboard-backed
+  query statistics, per-fingerprint summaries, query errors, anomalies, query
+  tags or tag groupings, or Postgres traffic budgets affecting a fingerprint.
+  Service tokens need `read_database` permission.
 - For Postgres, use CPU-sorted Insights data when diagnosing CPU pressure.
 - For sharded Vitess, review vindex usage per query pattern and the usage
   trend after index or routing changes.
@@ -102,6 +106,14 @@ Recommend production, staging, and short-lived development branches with safe mi
 
 Recommend when query patterns or growth suggest shard-awareness problems. Do not reshard automatically.
 
+### Read-only regions
+
+For Vitess databases with regional read traffic, analytics, agents, or other
+replica-suitable workloads, review read-only regions per keyspace, including
+cluster size and replica count. Recommend topology changes only with evidence
+from workload placement, query volume, latency, or availability requirements;
+do not apply read-only region size or replica changes automatically.
+
 ## Postgres-specific recommendations
 
 ### User-defined roles