Mark local skill builds with an OCI descriptor annotation

[samuv]

Summary

• Supersedes Hide pulled skill artifacts from local builds listing #4971. Same user-facing behaviour, different mechanism — following review feedback on the sidecar approach (discussion).
• GET /api/v1beta/skills/content and OCI-based install both tag the shared local OCI store as a cache — then ListBuilds (GET /api/v1beta/skills/builds) iterates every tag and reports them as local builds, so every previewed or installed remote skill pollutes the "what have I built locally?" view.
• Encode the "I built this locally" signal directly on the OCI artifact: a dev.stacklok.toolhive.local-build=true annotation stamped on the root-index descriptor entry in index.json when Build tags, and read back by ListBuilds as the filter.
• Pulled tags (install + content-preview) do not get the annotation — not by an explicit strip step, but because Registry.Pull tags by digest, and oras-go's oci.Store.Resolve returns a plain descriptor for digest references (annotations stripped). So pulled blobs stay in the OCI store as a cache but their tag is invisible to ListBuilds.
• Push is also safe: push resolves by digest too, so the local-build marker never crosses the wire and the pushed artifact digest matches the local one.

Why not a builds.json sidecar (the #4971 approach)?

Single source of truth, no sidecar to drift, no stale-entry pruning on list, no atomic-write path to maintain. Most importantly: no migration heuristic — #4971 had a looksLikePulledRef grandfather rule that could silently hide a pre-existing my-skill:v1.0.0 tag, which is a real failure mode. With annotations, pre-feature builds simply don't show up until rebuilt. Honest gap beats silent misclassification. As a bonus, the same marker composes with locally-built container images / MCP server images in the future, not just skills.

Type of change

• Bug fix (user-facing behaviour of ListBuilds / GET /api/v1beta/skills/builds)

Test plan

• Unit tests (go test ./pkg/skills/skillsvc/... -count=1)
• Full build (go build ./...)
• TestBuild_StampsLocalBuildAnnotation inspects index.json directly to confirm the annotation lands on the descriptor entry after Build
• TestDeleteBuild/delete_removes_local-build_marker_from_index.json confirms the annotation disappears with the tag
• TestGetContent/remote_pull_does_not_pollute_ListBuilds and TestInstallFromOCI_DoesNotLeakIntoListBuilds simulate the real Pull tagging side-effect and assert ListBuilds stays empty

Changes

File	Change
pkg/skills/skillsvc/local_build_marker.go	New: LocalBuildAnnotation constant + tagAsLocalBuild / isLocalBuild helpers. Uses store.Target().Resolve / .Tag to round-trip the descriptor annotation through index.json.
pkg/skills/skillsvc/build.go	Build calls tagAsLocalBuild instead of ociStore.Tag. ListBuilds iterates ListTags and filters by isLocalBuild before the usual metadata enrichment. DeleteBuild is unchanged; the annotation disappears with the descriptor entry.
pkg/skills/skillsvc/content.go	Intent-documenting comment at the registry.Pull site: pulled tags are invisible to ListBuilds because Pull tags by digest, which yields a plain descriptor.
pkg/skills/skillsvc/install_oci.go	Same intent-documenting comment at the install pull site.
pkg/skills/skillsvc/build_test.go	Switch existing Build/ListBuilds/DeleteBuild tests to use tagAsLocalBuild where they previously called ociStore.Tag. New TestBuild_StampsLocalBuildAnnotation (reads index.json) and updated TestDeleteBuild case. New TestListBuilds cases for pulled-tag hiding and the pull + build mix.
pkg/skills/skillsvc/content_test.go	New remote pull does not pollute ListBuilds case.
pkg/skills/skillsvc/install_oci_test.go	New TestInstallFromOCI_DoesNotLeakIntoListBuilds.

Does this introduce a user-facing change?

Yes — the response of GET /api/v1beta/skills/builds changes.

• Before: any skill pulled by install or by the content API appeared as a local build, because the endpoint listed every tag in the shared OCI store.
• After: only skills produced by thv skill build (or equivalent POST /api/v1beta/skills/build) appear. Pulled skills stay on disk as a cache (transparent speed-up for re-previews / re-installs) but are no longer surfaced as builds.

Migration note

Unlike #4971, there is no automatic migration. Tags that exist in the OCI store from before this change lack the new annotation and therefore will not appear in ListBuilds until they are rebuilt with thv skill build. This is a deliberate trade-off: it eliminates the heuristic (looksLikePulledRef) that could misclassify an already-pulled fully-qualified tag as a "grandfathered build", at the cost of a one-time visibility gap for pre-feature local builds.

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.99%. Comparing base (4e5301d) to head (0471ca5).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/skills/skillsvc/local_build_marker.go	47.05%	6 Missing and 3 partials ⚠️
pkg/skills/skillsvc/build.go	64.28%	3 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5000      +/-   ##
==========================================
- Coverage   69.04%   68.99%   -0.06%     
==========================================
  Files         553      554       +1     
  Lines       73016    73056      +40     
==========================================
- Hits        50414    50404      -10     
- Misses      19601    19649      +48     
- Partials     3001     3003       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JAORMX]

LGTM, do we want to remove the local build annotation when doing push?

[samuv]

LGTM, do we want to remove the local build annotation when doing push?

I don't think we need that, If I understand correctly our Push path resolves by digest, which strips annotations