feat(aca-sandboxes): use metadata URL for Swagger and operation discovery

[prjhawar]

Closes #129

Replaces the legacy ARM managedApis apiOperations/export endpoints with the connection's runtime metadata URL (apim -> metadata + ?export=true) for all Swagger and operation discovery in the aca-sandboxes skill.

Auth model

This skill targets the design experience from outside the sandbox, so swagger discovery uses:

• User-ACL on the connection (idempotent — GET first, PUT only if missing)
• API Hub token (az rest --resource "https://apihub.azure.com")

Highlights

• All apiOperations and ARM managedApis?export=true URLs replaced with the metadata URL pattern
• New references/swagger-discovery.md as the single source of truth for fetch + auth + parsing + operation matching
• Added idempotent user-ACL creation pattern (GET first, PUT only if missing) — scoped to user-ACL only
• Added 'Narrate progress' rule so the agent announces each step with URL/objectId in chat (not just inside collapsed shell blocks)
• Trimmed SKILL.md descriptions to stay under the 1024-char dev-time loader limit (--plugin-dir enforces this; marketplace install does not — but the trim keeps local dev unblocked)

Scoped to aca-sandboxes skill. connectors skill is unchanged except for the same description trim (also needed for --plugin-dir loading).

[Copilot]

Pull request overview

This PR updates the aca-sandboxes skill to use the connection’s runtime metadata URL (/apim/ → /metadata/ + ?export=true) for Swagger retrieval and operation/trigger discovery, replacing legacy ARM managedApis/* discovery endpoints. It also refreshes the skill documentation to describe both inside-sandbox (egress proxy) and outside-sandbox (user-ACL + API Hub token) auth paths and fixes the Swagger parsing expectations (top-level paths).

Changes:

• Replaced legacy managedApis/.../apiOperations and managedApis?...&export=true patterns with metadata URL–based Swagger fetch for operation and trigger discovery.
• Updated docs to include outside-sandbox exploration/testing guidance (user-ACL + az rest --resource https://apihub.azure.com) and an idempotent ACL creation pattern.
• Updated the trigger getting-started script to discover trigger operations by filtering Swagger paths for x-ms-trigger.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
plugin/skills/connectors/SKILL.md	Trims/reformats the connectors skill description/trigger keywords.
plugin/skills/aca-sandboxes/SKILL.md	Updates core skill guidance to use metadata URL for Swagger/operation discovery; adds narration + ACL idempotency guidance; updates step flow text.
plugin/skills/aca-sandboxes/scripts/trigger-getting-started.py	Switches trigger operation discovery to metadata Swagger + x-ms-trigger filtering; extends az_rest to support --resource.
plugin/skills/aca-sandboxes/references/trigger-setup.md	Replaces legacy trigger operation discovery with metadata Swagger filtering; adds outside-sandbox user-ACL + API Hub token flow.
plugin/skills/aca-sandboxes/references/trigger-flow.md	Updates optional trigger discovery and troubleshooting notes to reference metadata Swagger instead of legacy endpoints.
plugin/skills/aca-sandboxes/references/runtime-url-examples.md	Documents inside/outside sandbox auth contexts and updates operation discovery guidance to metadata Swagger.
plugin/skills/aca-sandboxes/references/quickstart.md	Updates “discover operations” quickstart guidance to use metadata Swagger (inside/outside patterns).
plugin/skills/aca-sandboxes/references/handler-guide.md	Adds an explicit “fetch Swagger first” step using metadata URL from inside sandbox.
plugin/skills/aca-sandboxes/references/gateway-connections.md	Adds a note about operating from inside the sandbox once wired (but currently mischaracterizes dynamicInvoke).
plugin/skills/aca-sandboxes/references/dynamic-values.md	Fixes Swagger parsing to use top-level paths and updates fetch instructions to metadata URL.
plugin/skills/aca-sandboxes/references/direct-api.md	Reworks Swagger fetch and operation-finding guidance around metadata URL; adds outside-sandbox user-ACL + API Hub token flow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

[apranaseth]

Could you address comments

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.