docs: release-review fixes — CHANGELOG completeness + measured caching claims

From the v0.9.2 multi-persona release review:

- CHANGELOG now covers all user-facing changes in this release: humanized
  tool-call titles + source badges (#980) and legacy docs-URL
  canonicalization (#1004) were missing entirely (PM P0).
- The model-removal entry names the exact error users with pinned removed
  IDs will see and points at the altimate-code.json escape hatch (PM P1).
- Cortex caching claims softened from a flat "90% discount" to Snowflake's
  reduced cached-input rate with workload-dependence caveats, and a note
  that cache_read_input/cache_write_input telemetry columns begin
  populating (previously always NULL) so admin dashboards aren't surprised
  (PM P2, Chaos Gremlin P1/P2).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: anandgupta42

CHANGELOG.md

@@ -10,14 +10,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Snowflake Cortex: `claude-sonnet-5`, `claude-opus-4-8`, and OpenAI GPT-5.4 (`openai-gpt-5.4`, `-mini`, `-nano`) in the model picker.** All verified live against Cortex, including prompt caching and tool calling on the new Claude models.
+- **Human-readable tool-call titles and source badges.** Tool calls now render dbt-aware labels — "Reading customers model", "Searching \*\*/\*.sql" — instead of raw paths, and every call carries an authoritative source badge (`builtin` / `altimate` / `mcp`) stamped server-side so all clients (chat webview, TUI) display consistent origins. (#980)
 
 ### Changed
 
-- **Snowflake Cortex model catalog refreshed against the live service (2026-07-20).** Removed models Snowflake has deprecated (July 8, 2026: `deepseek-r1`, `mistral-large`, `llama3.1-405b`, `snowflake-llama-3.3-70b`) or delisted (`claude-3-7-sonnet`, `claude-3-5-sonnet`, `openai-gpt-5-chat`, `llama4-scout`, `mixtral-8x7b`, `snowflake-llama-3.1-405b`, `gemini-3.1-pro`) — requests to these now hard-fail on Cortex. Locally registered models via `altimate-code.json` are unaffected.
+- **Snowflake Cortex model catalog refreshed against the live service (2026-07-20).** Removed models Snowflake has deprecated (July 8, 2026: `deepseek-r1`, `mistral-large`, `llama3.1-405b`, `snowflake-llama-3.3-70b`) or delisted (`claude-3-7-sonnet`, `claude-3-5-sonnet`, `openai-gpt-5-chat`, `llama4-scout`, `mixtral-8x7b`, `snowflake-llama-3.1-405b`, `gemini-3.1-pro`) — requests to these now hard-fail on Cortex. **If your config pins one of these IDs, the next request fails with `Model not found: snowflake-cortex/<model>. Did you mean: ...?`** — switch to a current model, or re-register the ID via `altimate-code.json` (see the providers docs). Locally registered models are unaffected.
 
 ### Fixed
 
-- **Snowflake Cortex prompt caching now activates for Claude models.** Cortex only honors caching markers placed inside content blocks (`messages[].content[].cache_control`), but requests carried them as message-level fields — so every request billed the full input rate (`cache_read_input`/`cache_write_input` stayed NULL in `TOKENS_GRANULAR`). The provider now relocates the markers into content blocks (system prompt + trailing messages, max 4 breakpoints), cutting repeated-prefix input cost by up to 90% on long agent sessions. If a Cortex account rejects the marked shape, the request is retried once without markers and marker injection pauses for a 5-minute cooldown. (#1009)
+- **Snowflake Cortex prompt caching now activates for Claude models.** Cortex only honors caching markers placed inside content blocks (`messages[].content[].cache_control`), but requests carried them as message-level fields — so every request billed the full input rate (`cache_read_input`/`cache_write_input` stayed NULL in `TOKENS_GRANULAR`). The provider now relocates the markers into content blocks (system prompt + trailing messages, max 4 breakpoints), so repeated prefixes bill at Snowflake's reduced cached-input rate — savings are workload-dependent and largest on long agent sessions with big stable prefixes. If a Cortex account rejects the marked shape, the request is retried once without markers and marker injection pauses for a 5-minute cooldown. Note for Snowflake admins: `cache_read_input`/`cache_write_input` in `TOKENS_GRANULAR` begin populating for these workloads (previously always NULL) — update any dashboard queries that assumed those columns were NULL. (#1009)
+- **Legacy documentation links canonicalized.** `docs.altimate.sh`, `datamates-docs.myaltimate.com`, and `www.altimate.sh/benchmarks` references (including the TUI's docs links and system prompts) now point to `help.altimate.ai` and `altimate.ai/benchmarks`. (#1004)
 
 ## [0.9.1] - 2026-07-08
 

docs/docs/configure/providers.md

@@ -276,7 +276,7 @@ Create a PAT in Snowsight: **Admin > Security > Programmatic Access Tokens**.
 
 Billing flows through your Snowflake credits — no per-token costs.
 
-Prompt caching is applied automatically for Claude models: cache markers are placed on the system prompt and trailing messages, so repeated context in long sessions is billed at Snowflake's cached-input rate (a 90% discount on cache reads, 5-minute TTL). Cache activity appears as `cache_read_input`/`cache_write_input` in Snowflake's `CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY`/`TOKENS_GRANULAR` telemetry. OpenAI models are cached automatically by Cortex itself; other model families don't support caching.
+Prompt caching is applied automatically for Claude models: cache markers are placed on the system prompt and trailing messages, so repeated context in long sessions is billed at Snowflake's reduced cached-input rate (5-minute TTL; exact cache-read and cache-write rates vary by model — see Snowflake's Cortex pricing). Savings are workload-dependent: long agent sessions with large stable prefixes benefit most, while very short sessions may see little change — monitor `cache_read_input`/`cache_write_input` in Snowflake's `CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY`/`TOKENS_GRANULAR` telemetry after upgrading (these columns were previously always NULL for altimate-code workloads and now populate). OpenAI models are cached automatically by Cortex itself; other model families don't support caching.
 
 **Available models** (catalog verified live against Cortex on 2026-07-20):