> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 05 PROVIDER AND AGENTS UPDATE

# 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.