[user-github-me]

Installing by tag requests a fresh registry index, but cached item manifests could hide newly added or removed tags for up to 24 hours. Pass skipCache through item and transitive-dependency resolution so an explicit refresh sees the current tags, dependencies, and file lists while retaining valid cached data if the fetch fails.

This update resolves the conflicts with current main and preserves its 32-request concurrency limit and switch to cached items after a timeout. cacheOnly takes precedence over a refresh request, so queued work does not restart network requests after that fallback has begun. The catalog contribution guide documents the resulting tag-install behavior.

Validation: full workspace build; CLI typecheck; all registry suites (273 passed, 1 skipped), including fresh/stale cache-only precedence, cached remaining items after a timeout, refreshed tags, and transitive dependencies; lint, formatting, test reachability, normal commit hooks, and both comment checks. Mint validation and link checks passed.

[jrusso1020]

Confirmed: tag install asks for a fresh index, but per-item manifests still come from the 24h cache, so new tags on existing items stay invisible for up to a day. Passing skipCache through to fetchItemManifest fixes that while keeping the offline stale fallback. Default callers are unchanged. Looks good.

— Rames

[jrusso1020]

Thanks for this, @user-github-me. This PR now has merge conflicts with main. Could you rebase it onto the latest main? Once it's conflict-free we'll review it and get it into the merge queue.

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 914bcd0.

Approve preview

[miguel-heygen]

Thanks for rebasing this. I re-read it at the new head since the earlier approval was on the first commit.

The conflict resolution looks right. In fetchItemManifest, cache-only mode still wins over a refresh request, so once a timeout has switched the remaining items to cache-only, a forced refresh does not restart network requests, and an uncached item in that mode still fails instead of fetching. Passing skipCache through loadAllItems and resolveItemWithDependencies covers the tag install path in add.ts and transitive dependencies, and the other callers of these functions (catalog, the studio panel, templates) keep the cache as before. The refreshed manifest is written back to the cache, so the per-item install that follows reads the new version. The tests go through resolveItemsByTag, which is what add calls, and CI is green on this head.

One non-blocking note: a tag install now refetches every item manifest in the registry rather than using a fresh cache (a few hundred requests on the default registry, 32 at a time). That only happens on the tag fallback and is what makes new tags visible, so I would keep it.

Verdict: APPROVE
Reasoning: The refresh is passed through every path a tag install uses, cache-only precedence after a timeout is kept, tests go through the real entry point, and CI is green with no conflicts.