Add entity provider implementation conventions to ai-integrations AGENTS.md #4781

What happened

PR #4779 added two entity provider packages (OCI skills and npx skills) to the ai-integrations workspace. The fullsend review (run 35003220422) found 10 issues (4 medium, 6 low), mostly about cross-provider inconsistencies — the OCI provider was missing timeouts, size limits, and pagination that the npx provider implements. However, the review missed three confirmed bugs: (1) the OCI source-location annotation uses oci: format instead of url:oci://, which the repo's own collectOciErrors.ts validator rejects at ingestion time; (2) both providers' type: 'full' mutations with per-item error handling can delete all healthy entities on transient failures; (3) missing yarn.lock entries. SonarQube also failed the quality gate on 6.9% code duplication (threshold: 3%). The ai-integrations workspace AGENTS.md has general backend conventions (service-to-service auth, config visibility, ConfigReader edge cases) but nothing about entity provider implementation patterns.

What could go better

The root cause of both the flagged issues and the missed bugs is the absence of documented entity provider conventions in the workspace AGENTS.md. The review agent found inconsistencies between the two providers but lacked context about what the correct patterns are — particularly the Backstage url: prefix requirement for source-location annotations, which is enforced by existing code (collectOciErrors.ts) but not documented anywhere agents can reference. Seven of the 10 review findings and all 3 missed bugs map directly to undocumented entity provider conventions. The workspace already has 11 plugins including an existing entity provider (catalog-backend-module-model-catalog) with proper patterns, but these conventions are implicit rather than documented. Confidence is high: the evidence is verified against the code, and the pattern is clear — undocumented conventions lead to inconsistent implementations and review blind spots.

Proposed change

Add an "Entity provider conventions" section to workspaces/ai-integrations/AGENTS.md documenting: (1) Source-location format: All backstage.io/source-location annotations must use Backstage location-ref format with url: prefix (e.g., url:oci://registry/image not oci:registry/image), as enforced by collectOciErrors.ts. (2) Mutation error handling: Providers using type: 'full' must guard against emitting empty entity arrays on transient failures — if all individual skill fetches fail but the index/repository list succeeds, skip the mutation rather than replacing the catalog with an empty set. (3) Per-request timeout: Use AbortController with a 30-second timeout on individual HTTP requests, matching the npx-skills pattern. (4) Response size limits: Buffer and check response body size before JSON parsing, using the MAX_ARTIFACT_BYTES pattern. (5) Pagination: List API endpoints must handle pagination tokens/cursors. (6) Shared patterns: Common entity-building logic, fetch helpers, and name-normalization should live in catalog-ai-skills-common to reduce duplication across providers. (7) Reference implementation: Point to catalog-backend-module-model-catalog and its config.d.ts as the convention model for new providers.

Validation criteria

The next 3 entity provider PRs in the ai-integrations workspace should not have source-location format issues, missing timeout/size-limit patterns, or unsafe full-mutation semantics flagged by the review agent. The SonarQube duplication gate should pass when new providers follow the shared-pattern guidance.

Generated by retro agent from #4779