​

Provider And AGENTS Update

​

Objective

Finish the migration by updating provider behavior, documenting the new rules, and adding guardrails for future work.

​

Query Client Provider

Current state:

• lib/react-query.tsx uses queryClient.clear() when the user changes

Target state:

• remove only user-scoped queries when the authenticated user changes
• preserve global/public cache when it is safe to do so

​

Provider Update Guidelines

• use the shared key model to identify user-scoped queries
• avoid nuking global market/reference data
• keep the behavior easy to reason about during sign-out/sign-in transitions

​

AGENTS.md Additions

Add a dedicated React Query section with these rules:

• use @/lib/cache-keys for all root key names
• use @/lib/query-keys for all query key arrays
• do not write inline query key arrays
• every user-scoped query must include userId at index [1]
• all reads belong in hooks/queries/
• all writes belong in hooks/mutations/
• pages/components should not call raw fetch for app data
• standard mutation pattern is useMutation with onSuccess invalidation
• do not use setQueryData or setQueriesData unless the project rule is explicitly revised
• review invalidation for overlap before adding new keys

​

Guardrails

Recommended follow-up guardrails:

• repo grep or lint check for inline queryKey: [
• repo grep or lint check for invalidateQueries({ queryKey: [
• repo grep or lint check for fetch( inside app/ and components/, excluding approved utility wrappers if needed

​

Verification

• authenticated smoke test
• sign-out and sign-in as another user
• React Query DevTools inspection
• final repo grep for inline keys, raw page/component fetch, and setQueryData usage