fix: use platform-appropriate model cache defaults

[leehack]

Summary

• Make the native DefaultModelDownloadManager() default match platform-appropriate cache behavior: desktop/server shared cache, mobile app-private temp/cache fallback, with temp fallback preserved for unusual desktop/server embedders that cannot expose a cache environment.
• Extend DefaultModelDownloadManager.auto(...) with optional androidAppPrivateCacheDirectory and iosAppPrivateCacheDirectory so apps can provide platform-specific mobile paths without constructor-level Platform.isAndroid / Platform.isIOS branching.
• Document default paths and migration guidance in README, website docs, changelog, and MIGRATION.md.

Platform defaults

• Linux: $XDG_CACHE_HOME/llamadart/models, or $HOME/.cache/llamadart/models when XDG_CACHE_HOME is unset.
• macOS: $HOME/Library/Caches/llamadart/models.
• Windows: %LOCALAPPDATA%\llamadart\models, then %APPDATA%\llamadart\models, then %USERPROFILE%\AppData\Local\llamadart\models.
• Android: androidAppPrivateCacheDirectory, then appPrivateCacheDirectory, then Directory.systemTemp/llamadart/models.
• iOS: iosAppPrivateCacheDirectory, then appPrivateCacheDirectory, then Directory.systemTemp/llamadart/models.
• Web: file-backed model cache remains unsupported; browser/runtime caches stay origin-scoped.

Compatibility / migration

• Source-compatible: existing public constructors and calls still compile.
• Additive API: androidAppPrivateCacheDirectory and iosAppPrivateCacheDirectory are optional named parameters.
• Potentially breaking behavior change: desktop/server DefaultModelDownloadManager() now prefers the shared cache instead of always using process temp.
• Potentially breaking behavior change: mobile DefaultModelDownloadManager.auto() without an explicit app-private path now falls back to best-effort temp/cache instead of throwing.
• MIGRATION.md documents how to preserve the old temp-cache behavior and how to update tests that expected the previous mobile throw.

Existing issue check

• Searched existing issues/PRs for DefaultModelDownloadManager cache path shared model cache appPrivateCacheDirectory; found prior related PR Add cross-platform model cache strategies #242, but no dedicated open issue to close.

Test Plan

Latest reviewed head: 4922f1c4febed3d13e230727a14d7de18595386c.

• dart format --output=none --set-exit-if-changed ... on changed Dart files
• git diff --check
• dart analyze — exits 0 with three pre-existing unrelated info lints
• dart test test/unit/platform/io/model_download_manager_io_test.dart — 61 tests passed
• dart test test/unit/core/models/download/model_download_manager_stub_test.dart — 4 tests passed
• dart test test/unit/core/models — 278 tests passed earlier in this PR loop
• dart test in example/basic_app
• flutter analyze && flutter test in example/chat_app
• External source-compat consumer in /private/tmp/llamadart_api_compat_review: dart pub get && dart analyze && dart run bin/compat.dart
• npm run build in website/
• Static scan: hardcoded_secrets=0, dangerous_exec=0, raw_url_logs=1 benign local-path message (source.path), no credential-bearing URL exposure
• GitHub CI on latest head: Analyze & Lint, Docs Build Check, Linux VM with Coverage, Web Chrome, Native macOS, Native Windows, Native Prompt Reuse Parity, companion package checks, and chat app preview all passed

Review notes

• Copilot review threads: 4 resolved, 0 unresolved.
• Reviewer blockers fixed during the PR loop: mobile fallback now preserves namespace; website docs no longer describe mobile auto(...) as throwing when it falls back.
• Final manual review also fixed stale mobile wording in public API docs/current website docs/chat app README so re-downloadable Flutter model storage points to app-specific cache rather than Documents.
• Known local model-store caveat: existing user-curated hardlink dedupe under ~/Library/Application Support/llamadart/models is a durable physical store, not automatically a package-managed cache root unless metadata entries are seeded. This is documented as a migration/local-store concern, not a blocker for the package default behavior.

[github-actions]

Chat app preview removed for leehack/llamadart-chat-pr-248.

[Copilot]

Pull request overview

Adjusts DefaultModelDownloadManager defaults to be platform-appropriate (shared per-user cache on desktop/server, app-private cache/temp fallback on mobile), adds optional platform-specific mobile directory parameters to auto(...), and updates docs + tests to match the new behavior.

Changes:

• Updated native IO DefaultModelDownloadManager() to prefer the platform’s implicit cache root (shared cache where supported; temp/cache fallback otherwise).
• Extended DefaultModelDownloadManager.auto(...) with androidAppPrivateCacheDirectory and iosAppPrivateCacheDirectory, plus new mobile fallback behavior when no app-private directory is provided.
• Refreshed README / website docs / migration notes and updated unit tests to cover the new defaults and namespace handling.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/src/platform/io/model_download_manager_io.dart	Implements new platform-appropriate default cache directory selection and expands auto(...) with platform-specific mobile directory parameters + fallback behavior.
lib/src/core/models/download/model_download_manager_stub.dart	Keeps non-IO stub API surface in sync by adding the new optional named parameters.
test/unit/platform/io/model_download_manager_io_test.dart	Adds/updates tests for constructor defaults, mobile fallbacks, namespace validation, and platform-specific mobile directory selection.
test/unit/core/models/download/model_download_manager_stub_test.dart	Verifies new auto(...) parameters compile on non-IO platforms and remain unsupported at runtime as expected.
README.md	Documents updated cache defaults and recommended usage patterns for cross-platform apps (including new mobile directory parameters).
website/docs/guides/model-lifecycle.md	Updates model cache guidance to reflect new auto(...) mobile behavior and constructor defaults.
MIGRATION.md	Adds migration guidance describing the runtime default changes and how to preserve previous temp-cache behavior.
CHANGELOG.md	Updates release notes text to describe the new default/cache behavior (currently placed under 0.8.8).
website/docs/changelog/recent-releases.md	Mirrors release note updates for the website’s “Recent Releases” page (currently placed under 0.8.8).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.