docs: document model lifecycle and deprecation

[mnkj0021]

Fixes #1275

Summary

• document how provider model scanners add, refresh, retire, and restore coding-agent models
• explain provider end-of-life metadata versus actual model disappearance
• distinguish Portal model selection (active model catalog) from request submission validation (agent supportedModels)
• document the disappearedAt 24-hour warning/rejection check as a secondary safety net rather than a guaranteed grace period
• explain default-model rotation and the effect on profiles, historical runs, and reproducibility
• add the guide to the docs sidebar and link it from the coding-agent guide

Validation

• before the latest documentation review follow-up: cd website && corepack pnpm build passed; 204 pages built and search index generated
• git diff --check passed
• latest review correction is on head 901f104
• current documentation/site workflows are action_required and need a Scope maintainer to approve the fork workflow run

No merge/rebase of main was performed for the review follow-up.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot review overview

🟡 Changes recommended

The documented 24-hour grace behavior is bypassed by current supported-model validation in common cases.

Review effort: Balanced
Findings: 1

Open (1)

• Portal uses active catalog instead of agent supportedModels · New

[Cedric Vidal (cedricvidal)]

Thanks for picking up #1275, this page is a useful addition. The structure reads well, the sidebar entry and cross-link are in the right place, and the site builds cleanly (215 pages locally). I checked each factual claim against the code. The sync, firstSeenAt/lastSeenAt, restore and auto-default parts are accurate. I have one naming request, and a few statements don't match what a user will actually see; the grace-window one is the most important of those.

1. Title: "Model catalog and lifecycle"

"Model lifecycle & deprecation" undersells the page. Most of it explains how scanners add and refresh models, how supportedModels is rebuilt, and how the default rotates. Deprecation is one section, and it's part of the lifecycle anyway. The sidebar label is what people scan when looking for "where do models come from", so it should cover discovery too.

"Catalog" matches the page's own wording ("Scope's model catalog") and how the docs already describe shared records. I'd avoid "library", because in the Portal that word means project-scoped content you author, while models are global and discovered. Please use:

• title: Model catalog and lifecycle in the frontmatter
• { label: 'Model catalog & lifecycle', slug: 'guides/model-lifecycle' } in astro.config.mjs
• the same name for the link text in choosing-a-coding-agent.md

Keep "deprecation" in the description: so the page still shows up in search.

2. The 24-hour grace window isn't what users hit in practice

The page says a newly disappeared model is still accepted with a warning for 24h. In the normal flow that can't happen:

1. POST /api/v1/models/sync sets disappearedAt and rebuilds supportedModels from active models only (models.ts).
2. On submit, validateAgentTarget runs first and rejects any model not in supportedModels with agent_model_unsupported (agent-helpers.ts#L93).
3. The disappearedAt warning / model_unavailable_for_worker check comes after that (requests/index.ts#L1075). It's only reached if supportedModels still lists the model, for example after a manual PUT/PATCH /api/v1/agents or a registration upsert that passes an explicit list.

So right after a scan drops a model, submissions fail immediately with agent_model_unsupported, not after 24h with model_unavailable_for_worker. Could you document it that way? Describe the disappearedAt warning and reject as a secondary safeguard for when the agent's list hasn't been reconciled yet. Whether the grace period should work end-to-end is a code question, and I'd track it in a separate issue rather than describe it here as current behavior.

3. Profiles: "prefer an active model" understates it

• Profile creation stores the resolved model (agentCheck.model ?? model in profiles.ts). If no model is given, the agent's current default is saved into the version. Existing profile versions are therefore not affected by default rotation, which is worth saying explicitly since the PR description promises the effect on profiles.
• A profile version whose model has disappeared can't be used for new runs or reruns. Both go through validateAgentTarget, so you get agent_model_unsupported. "Prefer an active model" should be "you must create a new profile version with a replacement model."

4. Default rotation does affect inline requests that omit model

Inline requests without a model resolve to agent.defaultModel at submission time (agent-helpers.ts#L102). When sync auto-rotates the default, those requests silently start running a different model. This is the main reproducibility caveat of default rotation. I'd add a line recommending an explicit model (or a profile) for benchmarks you intend to compare over time.

Smaller points

• "Scope keeps lifecycle history" overstates it. There's a single disappearedAt marker that gets $unset on restore, so earlier disappear/restore cycles aren't recorded. Suggest "Scope keeps the model record (marked as disappeared) rather than deleting it."
• "Planned for retirement" is in the numbered state list, but it's only metadata (providerEndOfLife) on an active model. I'd move it to a note under Active so readers don't look for a status filter for it.
• Restore doesn't restore the default. If the old default comes back, defaultModel stays on whatever was auto-selected while it was gone. Worth one sentence.
• Be concrete about providers. There are two scanners, Copilot and Anthropic. Only the Copilot scanner sends providerEndOfLife; Anthropic sends only providerAvailableFrom.
• Operator checklist: GET /api/v1/models accepts agentId, provider and status=active|disappeared. Using ?agentId=…&status=disappeared in step 2 makes the check quicker.

Points 1–4 are the ones I'd like addressed before merge. 1 decides how readers find the page, and 2–4 describe user-visible behavior differently from what the API does. The rest are optional polish.

[Cedric Vidal (cedricvidal)]

mnkj0021 Let ne know if those comments I made make sense :)