···11+# Repository Snapshot Cache Design
22+33+## Goal
44+55+Add a small startup cache that restores repository UI immediately on app launch, while keeping live repository discovery as the only source of truth.
66+77+## Principles
88+99+- Keep the cache disposable.
1010+- Keep the payload small and structural.
1111+- Do not let bad cache data affect settings loading.
1212+- Always run a normal live refresh after cache restore.
1313+- Only overwrite the cache after a complete successful live load.
1414+1515+## Storage
1616+1717+Use a standalone JSON file at `~/.prowl/repository-snapshot.json`.
1818+1919+Reasoning:
2020+2121+- Cache decode failures stay isolated from `settings.json`.
2222+- The file can be deleted safely with no migration burden.
2323+- The payload can evolve with an explicit schema version.
2424+2525+## Payload
2626+2727+Persist only data needed for first paint:
2828+2929+- repositories in UI order
3030+- repository root path
3131+- repository display name
3232+- worktree name
3333+- worktree detail string
3434+- worktree working-directory path
3535+- worktree `createdAt`
3636+3737+Do not cache:
3838+3939+- PR state
4040+- line changes
4141+- watcher state
4242+- notifications
4343+- `lastFocusedRepositoryID`
4444+4545+Selection restoration continues to use existing `lastFocusedWorktreeID` persistence.
4646+4747+## Invalidation
4848+4949+Treat the cache as a miss when any of the following happens:
5050+5151+- file is missing or empty
5252+- schema version mismatch
5353+- JSON decode failure
5454+- any cached repository root path no longer exists
5555+- any cached worktree path no longer exists
5656+5757+When invalid, discard the cache file and continue with a normal live load.
5858+5959+## Startup Flow
6060+6161+1. Load pinned/archive/order/last-focused persisted state.
6262+2. Load repository snapshot cache.
6363+3. If snapshot exists, restore repositories into state immediately.
6464+4. Mark initial load complete so the main UI renders.
6565+5. Start the usual live repository loading flow.
6666+6. Apply live results to the UI.
6767+7. If the live load succeeds with no repository failures, overwrite the snapshot file.
6868+6969+## Refresh Rules
7070+7171+Overwrite the snapshot only after complete successful repository loads:
7272+7373+- initial startup refresh
7474+- manual refresh
7575+- other flows that end in a full successful repository snapshot
7676+7777+Do not overwrite the snapshot on partial or failed loads.
7878+7979+No TTL is needed because the cache is only a startup accelerator. Freshness comes from the unconditional live refresh that always runs after startup.