opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/aws-sst-development/references/deploy-and-troubleshoot.md

@@ -0,0 +1,182 @@
+# Deploying and operating SST v4 stacks
+
+The deploy/operate half of the lifecycle: running deploys safely, recovering from
+failures, migrating resources, and the operational contracts (durable aliases,
+observability) that keep a deployed stack healthy. Read `authoring.md` for how to
+*write* the resources; this is about getting them live and keeping them live.
+
+## Table of contents
+
+- [The deploy commands](#the-deploy-commands)
+- [Before every deploy](#before-every-deploy)
+- [Resource-type migrations: never single-PR](#resource-type-migrations-never-single-pr)
+- [Renaming a physical name within the same type](#renaming-a-physical-name-within-the-same-type)
+- [Pulumi state hygiene after a failed deploy](#pulumi-state-hygiene-after-a-failed-deploy)
+- [Durable Lambda alias contract](#durable-lambda-alias-contract)
+- [Observability as a merge gate](#observability-as-a-merge-gate)
+- [CI trigger gotcha](#ci-trigger-gotcha)
+
+## The deploy commands
+
+All via the project's package manager (`npx`, `pnpm exec`, or an npm script —
+check `package.json`). From the project root unless the SST app lives in a
+subdir:
+
+| Command | What it does |
+|---------|--------------|
+| `npx sst dev` | Live-reload dev mode; Lambdas run locally against real AWS resources. |
+| `npx sst diff --stage <stage>` | Preview the plan (create/update/delete) without applying. Run this before any real deploy. |
+| `npx sst deploy --stage <stage>` | Apply the plan to AWS. |
+| `npx sst remove --stage <stage>` | Tear down the stack (blocked on `protect: true` stages). |
+| `npx sst state ...` | Inspect/repair Pulumi state — see hygiene below. |
+
+`--stage` controls the deployment target. `prod` is special (retain/protect);
+ephemeral `pr-<n>` stages back PR previews and must work from a cold start.
+
+## Before every deploy
+
+1. **Confirm the target account.** `aws sts get-caller-identity` — a deploy goes
+   wherever your credentials point. The skill's PreToolUse hook surfaces the
+   account once per session; still eyeball it for prod.
+2. **Run `npx sst diff`** and read the plan. Look for unexpected **replacements**
+   (Pulumi printing `+-` / "replace") — a replacement on a stateful resource
+   (bucket, table) means data loss or a name rotation. If you see one you didn't
+   intend, stop and find out why (usually a changed logical name or an immutable
+   field).
+3. **Type-check and test** — `tsc --noEmit` and the infra Vitest suite
+   (`testing.md`). The `Output<T>` interpolation bug type-checks clean but fails
+   at deploy, so green types are necessary, not sufficient.
+4. **Flag irreversibility to the user** for prod deploys, `sst remove`, and any
+   migration. State the account and stage.
+
+## Resource-type migrations: never single-PR
+
+**Rule: when an existing AWS resource changes Pulumi *type* — e.g.
+`aws.cloudcontrol.Resource` → typed `aws.bedrock.AgentcoreGateway`, or any change
+of the type token at the same logical name — never put the destroy of the old
+resource and the create of the new one in the same PR/deploy.** Split into two
+sequential deploys:
+
+1. **PR-A (teardown):** remove *only* the old resource declaration. Deploy
+   destroys the AWS resource cleanly, freeing the AWS-side name.
+2. **PR-B (recreate):** introduce the new typed resource. Deploy creates into a
+   clean namespace — no conflict.
+
+### Why
+
+Pulumi treats a type change as **create-new + destroy-old, and creates first**.
+If the AWS-side name (anything that must be unique per account — an AgentCore
+Gateway, an IAM role, an S3 bucket, an ECR repo) is still owned by the old
+resource at create time, the deploy fails with `ConflictException` /
+`ValidationException` / 409 / 400 and leaves the stack half-deployed.
+
+- `replaceOnChanges: [...]` + `deleteBeforeReplace: true` **only work within one
+  resource type.** For a type-token change Pulumi sees two unrelated resources, so
+  they do nothing.
+- `dependsOn` doesn't help either — there's no source-side handle on the
+  not-yet-deleted old resource.
+
+### The cost, and how to plan it
+
+The price is a **gap window** between PR-A's deploy finishing and PR-B's deploy
+finishing, during which the AWS resource doesn't exist. For a public surface
+(e.g. a gateway URL) that's downtime.
+
+- Open PR-B back-to-back and have it ready to merge the instant PR-A's deploy
+  completes.
+- Notify external consumers if the resource is user-facing.
+- Internal tooling that resolves the resource via SSM self-heals on next call.
+
+This pattern turns a non-deterministic outage into a planned ~minutes window.
+
+## Renaming a physical name within the same type
+
+Even when the type is unchanged and Pulumi *would* support `deleteBeforeReplace`,
+prefer two reversible steps over a single delete-before-replace:
+
+1. PR-A: rename to a temporary distinct physical name.
+2. PR-B: rename back to the desired physical name.
+
+Single-step renames that depend on `deleteBeforeReplace` work in theory but are
+sensitive to AWS-side delete latency that can outlast Pulumi's update timeout,
+leaving you stuck mid-replace.
+
+## Pulumi state hygiene after a failed deploy
+
+When a deploy fails mid-flight, inspect state before re-running:
+
+```bash
+# (use the repo's package manager; -C infra if the app is in a subdir)
+npx sst state export --stage <stage> > /tmp/state.json
+jq '.latest.resources | map(.urn)' /tmp/state.json | grep <relevant-name>
+```
+
+- A failed **Create** usually leaves *no* partial entry — Pulumi's rollback is
+  clean; just fix the cause and re-deploy.
+- A failed **Delete** may leave the entry in state while the AWS resource is
+  already gone. Recovery is `sst state remove <urn>` (not hand-editing the JSON).
+- **Do not** edit the exported state file and re-import. Use `sst state remove` /
+  `pulumi import` for state surgery — manual edits corrupt the checkpoint.
+
+**Always delete the exported state file when done** — it contains account IDs and
+identifiers that must not linger:
+
+```bash
+rm -f /tmp/state.json
+```
+
+## Durable Lambda alias contract
+
+(Applies only to projects using durable/long-running Lambdas — `durable: true`.)
+
+**Invoke durable Lambdas through a published alias (`live`), never `$LATEST`.**
+Every `UpdateFunctionConfiguration` advances `$LATEST` and silently orphans
+in-flight durable executions started against the prior code — no `Errors` metric,
+no `FunctionError`, they just vanish. When adding a `durable: true` Lambda:
+
+1. Provision an `aws.lambda.Alias` named `live` next to the function (raw Pulumi —
+   SST has no first-class alias), with `{ ignoreChanges: ["functionVersion"] }`
+   so deploys don't reconcile the rotation script's writes back. The bootstrap
+   target is the sharp part: a fresh stage has no numbered version yet, so you
+   either (a) point the alias at `"$LATEST"` as a placeholder and let the
+   post-deploy rotation move it to a numbered version (verify your AWS region
+   accepts `$LATEST` on `CreateAlias` — some setups reject it), or (b) publish a
+   numbered version first (`aws.lambda.FunctionVersion`, or a CLI
+   `publish-version`) and point the alias at `"1"`. Either way, `ignoreChanges`
+   keeps subsequent deploys from clobbering the rotated value.
+2. Have the deploy pipeline run `aws lambda publish-version` +
+   `update-alias --name live` *after* every deploy (prod and preview, so previews
+   exercise the same contract).
+3. Source any build identity (commit SHA, feature flag) at *runtime*, not in the
+   Lambda env — otherwise every deploy advances `$LATEST` even with no code change.
+
+## Observability as a merge gate
+
+These projects require every new Lambda / queue / schedule to ship with
+monitoring *before* merge — cheap insurance against a silent prod regression.
+Whether you enforce it is per-project, but the checklist is sound:
+
+- **New Lambda?** Add it to an error-alarm segment in `infra/observability.ts`
+  (keep the segment map `as const` so a typo fails at typecheck, not at the pager).
+- **Structured logging.** Use Powertools `Logger` (set `POWERTOOLS_SERVICE_NAME`);
+  emit `service` + `errorType` on error paths. Avoid bare `console.error` in
+  Lambda code — it bypasses the JSON formatter your metric filters match on.
+- **Custom metrics carry a `stage` dimension** and alarms filter on the literal
+  `stage: "prod"`. Without this, a `pr-<n>` preview Lambda writes into the same
+  metric slot as prod and trips a prod alarm on preview traffic. Set the `stage`
+  dimension as a Powertools *default dimension* (read once from `process.env.STAGE`)
+  so "forgot to tag stage" is structurally impossible; hard-code `"prod"` in the
+  alarm (not `${stage}`) so preview alarms don't page.
+- **DLQs / Step Functions / schedules** each get a failure alarm, ideally rolled
+  into a composite pipeline-health alarm.
+- **Set `treatMissingData: "notBreaching"`** on alarms so a quiet metric doesn't
+  alarm on absence.
+
+## CI trigger gotcha
+
+A common GitHub Actions deploy workflow declares
+`on: pull_request: types: [opened, synchronize, reopened, closed]` — note there's
+no `edited`. So `gh pr edit <num> --base main` (re-basing a stacked PR onto main)
+does **not** re-trigger the deploy workflow. Force it with a rebase + force-push
+(fires `synchronize`) or an empty commit (`git commit --allow-empty`). This bites
+when you stack infra PRs for a two-PR migration.

package/bundled-skills/aws-sst-development/references/testing.md

@@ -0,0 +1,126 @@
+# Testing SST v4 infra
+
+A plain `import` of an infra module under bare `vitest` fails — `new
+sst.aws.Bucket(...)` expects a Pulumi engine that isn't running. You have two
+ways to test infra, and they catch different things:
+
+1. **Source-level assertions** (the house-style default below) — load the
+   module's source *text* and assert on structural invariants (resource names,
+   index shapes, IAM scoping, SSM paths, runtime pins). A lightweight regression
+   net that catches "someone changed the GSI projection" or "someone dropped the
+   stage from the SSM prefix" at `vitest` time, long before a deploy.
+2. **Pulumi runtime mocks** (`@pulumi/pulumi/runtime` `setMocks`) — actually
+   construct the resources under a mock engine and assert on the resulting graph
+   (resolved property values, dependency edges). Heavier to set up, but it tests
+   *behavior*, not just text — use it when a module has real branching logic.
+
+Source assertions are the common case because most infra modules are
+declarative; reach for Pulumi mocks when the *logic* (not just the declaration)
+is what you need to pin. This is a testing-strategy choice, not an SST
+limitation.
+
+## Setup
+
+`infra/vitest.config.ts`:
+
+```ts
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+  test: { include: ["tests/**/*.test.ts"], environment: "node" },
+});
+```
+
+Tests live in `infra/tests/<module>.test.ts`. Run with `npx vitest run` (or the
+repo's `test` script — check `package.json`; the infra suite may be a separate
+workspace from the application tests).
+
+## The source-assertion pattern
+
+Read the module source once, then assert with `toContain` / `toMatch`:
+
+```ts
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const src = readFileSync(path.resolve(__dirname, "../storage.ts"), "utf-8");
+
+describe("infra/storage.ts — resource surface", () => {
+  it("uses sst.aws.Dynamo (not raw Pulumi) for the items table", () => {
+    expect(src).toContain('new sst.aws.Dynamo("Items"');
+  });
+
+  it("declares the by-status GSI sparse with keys-only projection", () => {
+    const block = src.slice(src.indexOf('"by-status"'));
+    expect(block).toMatch(/hashKey:\s*"status"/);
+    expect(block).toMatch(/projection:\s*"keys-only"/);
+  });
+
+  it("never opts a bucket into public read", () => {
+    // SST defaults to block-public; this guards against a stray { public: true }.
+    expect(src).not.toMatch(/public:\s*true/);
+  });
+
+  it("builds the SSM prefix from $app.stage (no hardcoded stage)", () => {
+    expect(src).toContain("/my-app/${stage}/storage");
+    expect(src).toContain("$app.stage");
+  });
+});
+```
+
+Tips that make these tests pull their weight:
+
+- **Scope a `src.slice(...)` to the relevant block** before asserting, so a match
+  can't accidentally pass against a *different* resource elsewhere in the file
+  (e.g. slice from the `EpisodesV2` declaration to the next one before asserting
+  its GSIs).
+- **Count occurrences** to pin cardinality — e.g.
+  `expect(src.match(/^ssmParam\(/gm)?.length).toBe(9)` catches a dropped or
+  duplicated export. Use `^`-anchored multiline regex so the helper *definition*
+  isn't counted as a call.
+- **Write regression guards as negative assertions** — `expect(src).not.toMatch(
+  /new sst\.aws\.Dynamo\("Items"[^V]/)` proves the pre-migration table is gone.
+- **Pin numeric/string tunables via an exported `__test__` object.** When a module
+  has knobs (memory, timeout, model id), export them and assert both the constant
+  *and* its presence in the source, so a value change can't silently drift from
+  the test contract:
+
+  ```ts
+  // infra/query.ts
+  export const __test__ = { LAMBDA_MEMORY_MB: 2048, LAMBDA_TIMEOUT: "2 minutes" };
+  // infra/tests/query.test.ts
+  import { __test__ } from "../query";
+  it("pins 2 GB memory", () => {
+    expect(__test__.LAMBDA_MEMORY_MB).toBe(2048);
+    expect(src).toContain(`${__test__.LAMBDA_MEMORY_MB} MB`);
+  });
+  ```
+
+## What's worth a test
+
+Prioritize invariants where a silent change is expensive:
+
+- **IAM scoping** — that a permission is scoped to an ARN, not `*`; that
+  `$interpolate` (not a plain template literal) wraps an Output in an ARN.
+- **Security defaults** — no `public: true` on buckets; no `$LATEST` invocation on
+  a durable Lambda (a grep guard, often run in CI rather than vitest).
+- **Schema shape** — DynamoDB key/GSI/projection/stream choices; these encode
+  access-pattern decisions that are costly to change post-deploy.
+- **Cross-module contracts** — SSM parameter paths and count (other tools depend
+  on the exact path), and that the stage is always derived, never hardcoded.
+- **Runtime/bundle invariants** — that the Node runtime is pinned and (if the
+  banner-strip applies) that no bundle ships the colliding `__filename` const.
+  The bundle check naturally runs as a CI shell gate over
+  `.sst/artifacts/*-src/bundle.mjs` after a build, complementing the source tests.
+
+## What not to test this way
+
+- **Whether the deploy actually works** — that's an integration concern. Use a
+  PR-preview stage + a post-deploy smoke test (invoke the Lambda, assert a 200)
+  rather than trying to simulate AWS in a unit test.
+- **AWS-side behavior** (does the GSI return the right items, does the IAM policy
+  actually allow the call) — verify against a real preview deploy.
+
+Source assertions tell you the *declaration* didn't drift. Preview deploys + smoke
+tests tell you the *deployment* is correct. You want both; they catch different
+failures.

package/bundled-skills/awt-e2e-testing/SKILL.md

@@ -17,7 +17,7 @@ AWT gives AI coding tools the ability to see and interact with web applications
 - The test flow depends on visual matching, OCR, or platform auto-detection instead of stable DOM selectors.
 - You want an E2E toolchain that can both execute tests and explain failures for AI coding workflows.
 
-## What works now
+## Upstream Advertised Capabilities
 - YAML scenarios → Playwright with human-like interaction
 - Visual matching: OpenCV template + OCR (no CSS selectors needed)
 - Platform auto-detection: Flutter, React, Next.js, Vue, Angular, Svelte
@@ -26,6 +26,12 @@ AWT gives AI coding tools the ability to see and interact with web applications
 - 5 AI providers: Claude, OpenAI, Gemini, DeepSeek, Ollama
 - Skill Mode: no extra AI API key needed
 
+## Execution Boundary
+
+This entrypoint does not bundle the AWT runtime or its YAML schema. Inspect the selected upstream revision and actual installed commands before authoring a scenario. The installation command above is an upstream option, not permission to change global skills. Prefer an explicitly authorized project-scoped installation.
+
+Confirm the target environment, test accounts, permitted browser actions and data retention. A checkout test can place orders or send notifications; use an isolated fixture environment and inspect effects before execution. Do not send screenshots, credentials or application data to a cloud provider without authorization. Record the actual scenario, runtime/version, observed result and artifact paths. If runtime is absent, return a draft and mark execution pending rather than inventing a pass.
+
 ## Links
 - Main repo: https://github.com/ksgisang/AI-Watch-Tester
 - Skill repo: https://github.com/ksgisang/awt-skill

package/bundled-skills/azd-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: azd-deployment
-description: "Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure."
+description: "Prepare and verify authorized Azure Container Apps deployments with azd. Use for azure.yaml, Bicep, remote builds, managed identity and post-deploy checks."
 risk: critical
 source: community
 date_added: "2026-02-27"
@@ -10,6 +10,10 @@ date_added: "2026-02-27"
 
 Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure.
 
+## Authorization and preparation
+
+Inspect existing project files and the active tenant, subscription and environment first. Provisioning, deployment, role assignments and hook execution change cloud resources and may incur costs. Prepare the exact diff, target, estimated impact and rollback plan; execute only when the user explicitly authorizes that deployment. Do not print environment values or credentials into shared logs.
+
 ## Quick Start
 
 ```bash
@@ -161,50 +165,19 @@ output SERVICE_BACKEND_URI string = backend.outputs.uri
 output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId
 ```
 
-## Idempotent Deployments
+## Deployment Repeatability
 
-### Why azd up is Idempotent
+### Reconciliation and revision changes
 
 1. **Bicep is declarative** - Resources reconcile to desired state
 2. **Remote builds tag uniquely** - Image tags include deployment timestamp
 3. **ACR reuses layers** - Only changed layers upload
 
-### Preserving Manual Changes
+### Preserve unmanaged changes deliberately
 
-Custom domains added via Portal can be lost on redeploy. Preserve with hooks:
-
-```yaml
-hooks:
-  preprovision:
-    shell: sh
-    run: |
-      # Save custom domains before provision
-      if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
-        az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
-          --query "properties.configuration.ingress.customDomains" \
-          -o json > /tmp/domains.json
-      fi
-
-  postprovision:
-    shell: sh
-    run: |
-      # Verify/restore custom domains
-      if [ -f /tmp/domains.json ]; then
-        echo "Saved domains: $(cat /tmp/domains.json)"
-      fi
-```
+Inventory custom domains, ingress, role assignments and other Portal-managed settings before preparing a deployment. Move desired settings into reviewed infrastructure code or prepare a specific restoration plan. Setting a property to `null` is not a general guarantee that Azure will preserve an out-of-band edit. Repeated deployment may create new image revisions and execute hooks again; inspect those effects rather than claiming every hook is idempotent.
 
-### Handling Existing Resources
-
-```bicep
-// Reference existing ACR (don't recreate)
-resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
-  name: containerRegistryName
-}
-
-// Set customDomains to null to preserve Portal-added domains
-customDomains: empty(customDomainsParam) ? null : customDomainsParam
-```
+Reference an existing container registry explicitly in the project's Bicep when it is meant to remain externally managed. Do not copy an incomplete module or overwrite unrelated settings to make a deployment succeed.
 
 ## Container App Service Discovery
 
@@ -220,10 +193,12 @@ env: [
 ]
 ```
 
-Frontend nginx proxies to internal URL:
+Configure the frontend proxy using the backend's verified internal hostname, scheme and port. Do not assume the illustrative Bicep `resourceToken` exists in your project or copy an undeclared nginx `$BACKEND_URL` variable. If using a template, validate the rendered nginx configuration before deployment.
+
 ```nginx
+# Schematic: replace this host with the approved internal endpoint.
 location /api {
-    proxy_pass $BACKEND_URL;
+    proxy_pass http://approved-internal-backend;
 }
 ```
 
@@ -248,6 +223,10 @@ hooks:
   postprovision:
     shell: sh
     run: |
+      set -eu
+      : "${BACKEND_PRINCIPAL_ID:?Set the reviewed backend principal ID}"
+      : "${OPENAI_RESOURCE_ID:?Set the approved OpenAI resource scope}"
+      : "${SEARCH_RESOURCE_ID:?Set the approved Search resource scope}"
       PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
       
       # Azure OpenAI access
@@ -255,13 +234,13 @@ hooks:
         --assignee-object-id "$PRINCIPAL_ID" \
         --assignee-principal-type ServicePrincipal \
         --role "Cognitive Services OpenAI User" \
-        --scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true
+        --scope "$OPENAI_RESOURCE_ID"
       
       # Azure AI Search access
       az role assignment create \
         --assignee-object-id "$PRINCIPAL_ID" \
         --role "Search Index Data Reader" \
-        --scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true
+        --scope "$SEARCH_RESOURCE_ID"
 ```
 
 ## Common Commands
@@ -270,7 +249,7 @@ hooks:
 # Environment management
 azd env list                        # List environments
 azd env select <name>               # Switch environment
-azd env get-values                  # Show all env vars
+azd show                            # Inspect project/resource information
 azd env set KEY value               # Set variable
 
 # Deployment
@@ -284,24 +263,39 @@ azd show                            # Show project status
 az containerapp logs show -n <app> -g <rg> --follow  # Stream logs
 ```
 
-## Reference Files
+## Post-Deployment Verification
 
-- **Bicep patterns**: See references/bicep-patterns.md for Container Apps modules
-- **Troubleshooting**: See references/troubleshooting.md for common issues
-- **azure.yaml schema**: See references/azure-yaml-schema.md for full options
+Do not report completion from the deployment command's exit code alone. Within the authorized target scope:
+
+1. Inspect `azd show` and compare the actual environment, resource IDs and service endpoints with the approved plan.
+2. Check the active Container Apps revision, image architecture, ingress and readiness using the installed Azure CLI's supported read-only commands. Record the observed revision and health state; do not assume a new revision is receiving traffic.
+3. Run project-owned smoke checks against explicitly approved endpoints. Verify the frontend/backend integration and identity-based access without creating paid transactions, sending messages or exposing real customer data.
+4. Verify required role assignments at their exact resource scopes. A failed permission check is a failure, not a reason to add a broader role automatically.
+5. Inspect bounded, redacted service logs and compare custom domains or other preserved settings with the pre-deploy inventory.
+6. If a check fails, stop further rollout, report the failed observation and use the reviewed rollback plan. Do not run destructive cleanup or delete resources as an automatic rollback.
+
+Record the deployment target, image/revision identity, checks actually performed, failures and unverified areas. Missing provider access means verification is incomplete. The hook example above requires its resource IDs to be defined explicitly and fails before role mutation when they are missing.
+
+## Local Resources
+
+No additional Bicep patterns, troubleshooting guide or schema file is bundled. Validate the project configuration against the installed Azure Developer CLI and current official Azure documentation before preparing deployment.
 
 ## Critical Reminders
 
-1. **Always use `remoteBuild: true`** - Local builds fail on M1/ARM Macs deploying to AMD64
+1. **Verify build architecture** - Use remote builds or an explicitly configured local target architecture; an ARM image may not match an AMD64 deployment.
 2. **Bicep outputs auto-populate .azure/<env>/.env** - Don't manually edit
-3. **Use `azd env set` for secrets** - Not main.parameters.json defaults
+3. **Protect secrets** - Use the project’s approved secret-management approach; never commit credentials, dump environment values or put secrets in parameter defaults.
 4. **Service tags (`azd-service-name`)** - Required for azd to find Container Apps
-5. **`|| true` in hooks** - Prevent RBAC "already exists" errors from failing deploy
+5. **Handle RBAC failures explicitly** - Verify an existing assignment before treating a duplicate as success; never suppress permission or configuration failures.
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+Use for an existing azd project targeting Azure Container Apps when reviewing infrastructure, build architecture, managed identity, authorized deployment or post-deployment verification.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Examples require project-owned modules, resource IDs and installed CLI versions; no complete application or infrastructure template is bundled.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+## Official command references
+
+Check the [Azure Developer CLI reference](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference) and [Container Apps workflow guide](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/container-apps-workflows) for the installed tool version. These links inform API/command verification, not permission to install tools or deploy resources.

package/bundled-skills/azure-ai-agents-persistent-java/SKILL.md

@@ -16,15 +16,15 @@ Low-level SDK for creating and managing persistent AI agents with threads, messa
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-ai-agents-persistent</artifactId>
-    <version>1.0.0-beta.1</version>
+    <version>1.0.0-beta.2</version>
 </dependency>
 ```
 
 ## Environment Variables
 
 ```bash
-PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
-MODEL_DEPLOYMENT_NAME=gpt-4o-mini
+export PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
+export MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
 ```
 
 ## Authentication
@@ -32,6 +32,9 @@ MODEL_DEPLOYMENT_NAME=gpt-4o-mini
 ```java
 import com.azure.ai.agents.persistent.PersistentAgentsClient;
 import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
+import com.azure.ai.agents.persistent.*;
+import com.azure.ai.agents.persistent.models.*;
+import com.azure.core.http.rest.PagedIterable;
 import com.azure.identity.DefaultAzureCredentialBuilder;
 
 String endpoint = System.getenv("PROJECT_ENDPOINT");
@@ -39,6 +42,11 @@ PersistentAgentsClient client = new PersistentAgentsClientBuilder()
     .endpoint(endpoint)
     .credential(new DefaultAzureCredentialBuilder().build())
     .buildClient();
+String modelDeploymentName = System.getenv("MODEL_DEPLOYMENT_NAME");
+PersistentAgentsAdministrationClient administration = client.getPersistentAgentsAdministrationClient();
+ThreadsClient threads = client.getThreadsClient();
+MessagesClient messageClient = client.getMessagesClient();
+RunsClient runs = client.getRunsClient();
 ```
 
 ## Key Concepts
@@ -58,23 +66,23 @@ The Azure AI Agents Persistent SDK provides a low-level API for managing persist
 
 ```java
 // Create agent with tools
-PersistentAgent agent = client.createAgent(
-    modelDeploymentName,
-    "Math Tutor",
-    "You are a personal math tutor."
+PersistentAgent agent = administration.createAgent(
+    new CreateAgentOptions(modelDeploymentName)
+        .setName("Math Tutor")
+        .setInstructions("You are a personal math tutor.")
 );
 ```
 
 ### 2. Create Thread
 
 ```java
-PersistentAgentThread thread = client.createThread();
+PersistentAgentThread thread = threads.createThread();
 ```
 
 ### 3. Add Message
 
 ```java
-client.createMessage(
+messageClient.createMessage(
     thread.getId(),
     MessageRole.USER,
     "I need help with equations."
@@ -84,20 +92,26 @@ client.createMessage(
 ### 4. Run Agent
 
 ```java
-ThreadRun run = client.createRun(thread.getId(), agent.getId());
+ThreadRun run = runs.createRun(new CreateRunOptions(thread.getId(), agent.getId()));
 
-// Poll for completion
+// Bound polling; a terminal non-success state is not a completed answer.
+long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(60);
 while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
+    if (System.nanoTime() > deadline) {
+        throw new IllegalStateException("Run polling timed out; inspect/cancel the owned run separately");
+    }
     Thread.sleep(500);
-    run = client.getRun(thread.getId(), run.getId());
+    run = runs.getRun(thread.getId(), run.getId());
 }
 ```
 
+Check the resulting status before reading a final response: `requires_action` needs an authorized tool-output handler; `failed`, `cancelled`, `expired` or other non-success states must be reported explicitly. A polling timeout does not cancel the cloud run.
+
 ### 5. Get Response
 
 ```java
-PagedIterable<PersistentThreadMessage> messages = client.listMessages(thread.getId());
-for (PersistentThreadMessage message : messages) {
+PagedIterable<ThreadMessage> messages = messageClient.listMessages(thread.getId());
+for (ThreadMessage message : messages) {
     System.out.println(message.getRole() + ": " + message.getContent());
 }
 ```
@@ -105,8 +119,8 @@ for (PersistentThreadMessage message : messages) {
 ### 6. Cleanup
 
 ```java
-client.deleteThread(thread.getId());
-client.deleteAgent(agent.getId());
+threads.deleteThread(thread.getId());
+administration.deleteAgent(agent.getId());
 ```
 
 ## Best Practices
@@ -123,7 +137,8 @@ client.deleteAgent(agent.getId());
 import com.azure.core.exception.HttpResponseException;
 
 try {
-    PersistentAgent agent = client.createAgent(modelName, name, instructions);
+    PersistentAgent exampleAgent = administration.createAgent(
+        new CreateAgentOptions(modelDeploymentName).setName("Example").setInstructions("Answer briefly"));
 } catch (HttpResponseException e) {
     System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage());
 }
@@ -137,9 +152,10 @@ try {
 | GitHub Source | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents-persistent |
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+Use when implementing or maintaining Java persistent-agent threads, messages, runs and administration with the preview SDK. The reviewed example uses beta.2 subclients, not direct CRUD methods on PersistentAgentsClient.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Operations create billable cloud resources, send prompts and retain thread data. Use an authorized project/model and explicit budgets; delete only resources created for the current run, preserve IDs on failure, and redact message/credential logs.
+- Snippets are sequential fragments inside application code, not a standalone compiled program. API shape was checked against [Microsoft’s beta.2 sample](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-agents-persistent_1.0.0-beta.2/sdk/ai/azure-ai-agents-persistent/src/samples/java/com/azure/ai/agents/persistent/AgentBasicSample.java) and preview reference; no cloud run was performed. Add compatible azure-identity and required dependencies using the project’s reviewed Azure BOM.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/azure-ai-projects-py/SKILL.md

@@ -5,6 +5,13 @@ risk: critical
 source: community
 date_added: "2026-02-27"
 ---
+## Bundled upstream support
+
+Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.
+
+## Restored helper safety
+
+`scripts/run_batch_evaluation.py` uploads the entire selected JSONL file to the configured Azure AI project, creates a remote evaluation and run, and may incur model or cloud charges. Before invocation, review the data classification and confirm the exact file, endpoint, deployment, evaluators, and expected cost with the user. Do not run it during documentation-only work.
 
 # Azure AI Projects Python SDK (Foundry SDK)