## TL;DR

Fetch the current docs, regenerate the client against the new version, and point the base URL at it. The agent cached an old copy, so the client targets a v2 the provider is deprecating.

Version-pin your docs fetch: never generate from a cache older than your last successful build, and check the deprecation headers on the old endpoints to know your deadline.

## Verbatim query

```text
agent generated from a cached copy of the docs  -  the provider had shipped v3 and the client targeted a deprecated v2
```

## Steps

1. Confirm which version the client targets
   Check the base URL and version prefix the generated client uses.
   Compare against the provider's current docs homepage for the latest version.
   Expected: You can state the client's version and the provider's current version; they differ.

2. Read the deprecation terms for the old version
   Check the changelog for the v2 sunset date and whether it is already returning errors.
   Look at response headers on v2 calls for deprecation or sunset warnings.
   Expected: You know whether v2 still works and how long you have.

3. Fetch fresh docs and regenerate
   Pull the current docs or spec directly from the provider - not from any local cache.
   Regenerate the client and diff it against the old one to see what changed.
   Expected: The new client targets the current version and the diff shows exactly what moved.

4. Update the base URL and auth
   Point the client at the new version's base path.
   Verify auth still works - new versions sometimes change the auth scheme.
   Expected: Calls to the new version return 2xx with valid auth.

5. Retire the old version on a schedule
   Ship the new client behind a flag if the integration is large.
   Set a reminder before the v2 sunset date so the old path is gone in time.
   Expected: All traffic runs on the new version before the sunset date.

## Use this when

- Your generated client hits a version the provider has deprecated or shut down
- The provider shipped a new major version and your client predates it
- Errors appeared with no client change right after a provider version announcement

## Not for this skill when

- Both client and docs are on the same version and calls still fail - that is a different bug
- The provider has no versioning and changed behavior in place - treat that as doc drift, not a version problem
- The failure is a 401 - auth changed between versions is possible, but verify auth separately first

## Variant phrasings

### client targets deprecated API version
Cached docs go stale quietly; the client looks fine until the provider starts sunsetting the old version.

### generated from old docs version
Any client generated from a cached spec carries the cache's age as a hidden risk.

### provider shipped v3 client still on v2
Major version gaps mean renamed fields and new required params - regenerate, do not patch around it.

## Why it happens

Docs caches are convenient and dangerous: the agent fetched the docs once, the provider shipped v3, and every regeneration since has reused the stale copy. The old version keeps working until the sunset date, then calls start failing. The fix is process, not code: always generate from a fresh fetch and treat the docs cache as a build input with a TTL.

## Edge cases

- Providers sometimes sunset without fully killing the old version - it returns errors on some endpoints but not others, which looks like random flakiness
- Auth schemes change between versions more often than field shapes do; verify auth on the new version before debugging payload shape
- If the spec URL itself is versioned, your fetch may be caching an old spec URL - verify the fetch source, not just the fetch time

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tWtiJLczR15rfyD4h-K0WQ