From 0b319915bc64dc112282da70421656a620b68155 Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Thu, 16 Oct 2025 22:31:37 -0500
Subject: [PATCH 1/8] export everything on default client

---
 src/main.ts | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index 2997f67..ef5464b 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -7,12 +7,28 @@ import { MutationAction, MutationData, MutationTagsContext, MutationTagsBeforeCo
 import { QueryAction, QueryData, QueryActionArgs, QueryTags, QueryOptions, Query, AwaitedQuery } from './types/query'
 import { QueryTag, QueryTagType, QueryTagCallback, QueryTagFactory } from './types/tags'
 
-const { query, useQuery } = createQueryClient()
+const {
+  query,
+  useQuery,
+  defineQuery,
+  setQueryData,
+  refreshQueryData,
+  mutate,
+  useMutation,
+  defineMutation,
+} = createQueryClient()
 
 export {
   createQueryClient,
   tag,
-  query, useQuery
+  query,
+  useQuery,
+  defineQuery,
+  setQueryData,
+  refreshQueryData,
+  mutate,
+  useMutation,
+  defineMutation
 }
 
 export type {

From 8f5eb6fac1100993e411ff199f75d9a4b399fda6 Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Thu, 16 Oct 2025 22:31:50 -0500
Subject: [PATCH 2/8] update queries to reflect recent changes to params syntax

---
 docs/core-concepts/queries.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/core-concepts/queries.md b/docs/core-concepts/queries.md
index 41b8e0c..4877072 100644
--- a/docs/core-concepts/queries.md
+++ b/docs/core-concepts/queries.md
@@ -9,7 +9,7 @@ function searchCats(breed?: string) {
   ...
 }
 
-const catsQuery = query(searchCats, ['Maine Coon'])
+const catsQuery = query(searchCats, () => ['Maine Coon'])
 ```
 
 ## Query Properties
@@ -29,7 +29,7 @@ const catsQuery = query(searchCats, ['Maine Coon'])
 The query includes `execute`, which can be called at any point to force the function to be called again.
 
 ```ts
-const catsQuery = query(searchCats, ['Ragdoll'])
+const catsQuery = query(searchCats, () => ['Ragdoll'])
 
 function refresh(): void {
   catsQuery.execute()
@@ -45,9 +45,9 @@ Note that if awaiting a query, any errors that occur will be thrown. Consider pl
 :::
 
 ```ts
-const regularQuery = query(searchCats, ['Persian'])
+const regularQuery = query(searchCats, () => ['Persian'])
 //     ^? data: Cat[] | undefined
-const awaitedQuery = await query(searchCats, ['Persian'])
+const awaitedQuery = await query(searchCats, () => ['Persian'])
 //     ^? data: Cat[]
 ```
 
@@ -68,7 +68,7 @@ By default a query that hasn't been executed (or hasn't finished executing) will
 
 ```ts
 const placeholder: Cat[] = []
-const catsQuery = await query(searchCats, ['Bengal'], { placeholder })
+const catsQuery = await query(searchCats, () => ['Bengal'], { placeholder })
 //     ^? data: Cat[]
 ```
 
@@ -77,7 +77,7 @@ const catsQuery = await query(searchCats, ['Bengal'], { placeholder })
 Automatically re-trigger the function on an interval. Value provided is time in milliseconds.
 
 ```ts
-const catsQuery = await query(searchCats, ['Persian'], { interval: 30_000 })
+const catsQuery = await query(searchCats, () => ['Persian'], { interval: 30_000 })
 // automatically calls `searchCats` when query is created, and then again every 30 seconds
 ```
 
@@ -86,7 +86,7 @@ const catsQuery = await query(searchCats, ['Persian'], { interval: 30_000 })
 Automatically re-try the function when an error occurs. By default the query will wait `500` milliseconds between retries.
 
 ```ts
-const catsQuery = query(searchCats, ['Siamese'], { retries: 3 })
+const catsQuery = query(searchCats, () => ['Siamese'], { retries: 3 })
 // will try to call `searchCats` a total of 3 times, waiting 500 MS between each attempt
 ```
 
@@ -94,7 +94,7 @@ Alternatively you can pass in `RetryOptions`, which allows you to specify both a
 
 ```ts
 const retries = { count: 1, delay: 1_000 }
-const catsQuery = query(searchCats, ['Siamese'], { retries: 3 })
+const catsQuery = query(searchCats, () => ['Siamese'], { retries: 3 })
 // will retry after 1,000 MS once if initial call fails
 ```
 

From 798051eef8ffeb10441c9fb3ea93de38c1436a4e Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Thu, 16 Oct 2025 22:32:04 -0500
Subject: [PATCH 3/8] updated page for tags & invalidation

---
 docs/compare-to-tanstack.md             |   2 +-
 docs/core-concepts/tags-invalidation.md | 428 +++++-------------------
 2 files changed, 90 insertions(+), 340 deletions(-)

diff --git a/docs/compare-to-tanstack.md b/docs/compare-to-tanstack.md
index 11941a9..2740554 100644
--- a/docs/compare-to-tanstack.md
+++ b/docs/compare-to-tanstack.md
@@ -1,3 +1,3 @@
 # Migrating from Tanstack
 
-- no keys, caches function + arguments by default
+- no keys (tags don't require user to adopt naming scheme), caches function + arguments by default
diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index 2522b9b..edfc9f3 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -1,402 +1,152 @@
 # Tags & Invalidation
 
-<!-- Tags provide a powerful way to organize and invalidate cached queries in Kitbag query. They allow you to group related queries and efficiently update your cache when data changes.
+When it comes time to refresh your query, there are a few options. First, each query has an `execute()` function, which will force the query to refetch and update the reactive `data` for your query but also any other query that shares the same function and arguments.
 
-## Creating Tags
+## refreshQueryData
 
-Use the `tag` function to create query tags:
+The `refreshQueryData` utility can also be used to invalidate queries based on action and args.
 
 ```ts
-import { tag } from '@kitbag/query'
-
-// Create tags for different data types
-const userTag = tag('user')
-const postTag = tag('post')
-const commentTag = tag('comment')
-const profileTag = tag('profile')
-```
-
-Tags should represent logical groupings of your data:
-
-```ts
-// Domain-based tags
-const userTag = tag('user')
-const orderTag = tag('order')
-const productTag = tag('product')
-
-// Feature-based tags
-const dashboardTag = tag('dashboard')
-const settingsTag = tag('settings')
-const reportsTag = tag('reports')
-```
-
-## Tagging Queries
-
-Add tags to your queries to group them logically:
-
-```ts
-const userQuery = query('user', fetchUser, {
-  tags: [userTag, profileTag]
-})
+import { refreshQueryData } from '@kitbag/query'
+import { searchCats } from '../services/catsApi'
 
-const userPostsQuery = query('user-posts', fetchUserPosts, {
-  tags: [userTag, postTag]
-})
+function handleRefreshClick(): void {
+  // invalidates all queries that call searchCats
+  refreshQueryData(searchCats)
 
-const postCommentsQuery = query('post-comments', fetchPostComments, {
-  tags: [postTag, commentTag]
-})
+  // invalidates only queries that call searchCats with ['Himalayan']
+  refreshQueryData(searchCats, () => ['Himalayan'])
+}
 ```
 
-## Cache Invalidation
-
-Invalidate all queries with specific tags:
-
-```ts
-import { createQueryClient } from '@kitbag/query'
+## Tags
 
-const { queryClient } = createQueryClient()
+Often we have multiple queries to different functions that are related to each other. For example, any queries that use the current user token in API headers would probably want to be called again if the token changes. Ideally these queries that are otherwise unrelated could be grouped together.
 
-// Invalidate all user-related queries
-queryClient.invalidate(userTag)
+Tags offer a way to not only organize related queries but also to set and invalidate a cache for queries you might not have direct access to. Think of `tag` as a function that generates a unique identifier that helps Kitbag Query to find the query later.
 
-// Invalidate multiple tags at once
-queryClient.invalidate([userTag, profileTag])
-```
+Since each tag generated is unique, we recommend creating and exporting your tags from a shared location.
 
-### Automatic Invalidation in Mutations
+::: code-group
 
-Set up automatic invalidation when mutations succeed:
+```ts [tags.ts]
+import { tag } from '@kitbag/query'
 
-```ts
-const updateUserMutation = query.mutation(
-  async (userData: UpdateUserData) => {
-    const response = await fetch(`/api/users/${userData.id}`, {
-      method: 'PUT',
-      body: JSON.stringify(userData)
-    })
-    return response.json()
-  },
-  {
-    // Automatically invalidate these tags on success
-    invalidateTags: [userTag, profileTag]
-  }
-)
+export const requiresUserContext = tag()
 ```
 
-## Tag Strategies
+:::
 
-### Hierarchical Tags
+Then from wherever queries are created the query options include `tags`, which expects an array of tags.
 
-Organize tags in a hierarchy for fine-grained control:
+::: code-group
 
-```ts
-// General to specific
-const dataTag = tag('data')
-const userDataTag = tag('user-data')
-const userProfileDataTag = tag('user-profile-data')
-
-const userProfileQuery = query('user-profile', fetchUserProfile, {
-  tags: [dataTag, userDataTag, userProfileDataTag]
-})
+```vue [components/UserProfile.ts]
+<script lang="ts" setup>
+import { useQuery } from '@kitbag/query'
+import { requiresUserContext } from '../tags'
+import { fetchMe } from '../services/userApi'
 
-// Invalidating dataTag invalidates everything
-// Invalidating userDataTag invalidates all user-related data
-// Invalidating userProfileDataTag invalidates only profile data
+const meQuery = useQuery(fetchMe, () => [], { tags: [requiresUserContext] })
+</script>
 ```
 
-### Entity-Based Tags
+```vue [components/NotificationsIndicator.ts]
+<script lang="ts" setup>
+import { useQuery } from '@kitbag/query'
+import { requiresUserContext } from '../tags'
+import { getNotifications } from '../services/notificationsApi'
 
-Tag queries by the entities they involve:
-
-```ts
-const userTag = tag('user')
-const postTag = tag('post')
-
-// Queries involving users
-const userQuery = query('user', fetchUser, { tags: [userTag] })
-const usersListQuery = query('users-list', fetchUsers, { tags: [userTag] })
-
-// Queries involving both users and posts
-const userPostsQuery = query('user-posts', fetchUserPosts, { 
-  tags: [userTag, postTag] 
-})
-
-// When a user is updated, all user-related queries are invalidated
-// When a post is created, all post-related queries are invalidated
+const notificationsQuery = useQuery(getNotifications, () => [], { tags: [requiresUserContext] })
+</script>
 ```
 
-### Feature-Based Tags
+:::
 
-Group queries by application features:
+Then later perhaps when the user token changes, you can access and invalidate the cache for this tag.
 
-```ts
-const dashboardTag = tag('dashboard')
-const analyticsTag = tag('analytics')
-const settingsTag = tag('settings')
-
-const dashboardDataQuery = query('dashboard-data', fetchDashboardData, {
-  tags: [dashboardTag]
-})
+::: code-group
 
-const userAnalyticsQuery = query('user-analytics', fetchUserAnalytics, {
-  tags: [dashboardTag, analyticsTag]
-})
+```ts [services/auth.ts]
+import { refreshQueryData } from '@kitbag/query'
+import { requiresUserContext } from '../tags'
 
-// Refresh entire dashboard
-queryClient.invalidate(dashboardTag)
+function onLoginSuccessful(): void {
+  // refreshes both meQuery and notificationsQuery
+  refreshQueryData(requiresUserContext)
+}
 ```
 
-## Advanced Invalidation Patterns
+:::
 
-### Conditional Invalidation
+## Tag Type
 
-Invalidate queries based on conditions:
+Kitbag Query also tracks a generic on each tag, which By default is `unknown`. This satisfies any query, but assigning your actual type not only validates the query type but also provides improved type safety later when accessing cached data, like in `setQueryData`
 
 ```ts
-const updateUserMutation = query.mutation(
-  async (userData: UpdateUserData) => {
-    const response = await fetch(`/api/users/${userData.id}`, {
-      method: 'PUT',
-      body: JSON.stringify(userData)
-    })
-    return response.json()
-  },
-  {
-    onSuccess: (data, variables) => {
-      // Always invalidate user data
-      queryClient.invalidate(userTag)
-      
-      // Conditionally invalidate based on what changed
-      if (variables.profilePicture) {
-        queryClient.invalidate(profileTag)
-      }
-      
-      if (variables.email) {
-        queryClient.invalidate(authTag)
-      }
-    }
-  }
-)
-```
+import { tag, setQueryData } from '@kitbag/query'
 
-### Partial Invalidation
+const catTag = tag<Cat>()
 
-Invalidate specific query instances:
-
-```ts
-// Invalidate user query for specific ID
-queryClient.invalidate(userQuery, [userId])
-
-// Invalidate all queries with userTag but only for specific parameters
-queryClient.invalidate(userTag, (query) => {
-  return query.params?.[0] === specificUserId
-})
+// data will be type `Cat`, return type for setter is expected to be `Cat` 
+setQueryData(catTag, (data) => ...)
 ```
 
-### Background Invalidation
-
-Invalidate without showing loading states:
-
-```ts
-// Silently refetch data in the background
-queryClient.invalidate(userTag, { refetchType: 'background' })
+## Tag Factories
 
-// Only invalidate, don't refetch
-queryClient.invalidate(userTag, { refetchType: 'none' })
-```
+Tags can also be configured as factories, which offer a way to increase specificity through a callback you define. For example, if you have a bunch of instances of a component that has a query and you want to selectively invalidate cache.
 
-## Tag Organization Patterns
+::: code-group
 
-### By Domain Model
+```vue [components/CatViewer.vue]
+<script lang="ts" setup>
+import { useQuery } from '@kitbag/query'
 
-Organize tags around your domain models:
+const { catId } = defineProps<{
+  catId: string
+}>()
 
-```ts
-// E-commerce example
-const userTag = tag('user')
-const productTag = tag('product')
-const orderTag = tag('order')
-const cartTag = tag('cart')
-const wishlistTag = tag('wishlist')
-
-// CMS example
-const pageTag = tag('page')
-const postTag = tag('post')
-const categoryTag = tag('category')
-const authorTag = tag('author')
-const mediaTag = tag('media')
+const query = useQuery(fetchCat, () => [catId])
+</script>
 ```
 
-### By Data Relationships
+:::
 
-Tag queries based on data relationships:
+If in another part of your application you update the cat model, you could instead define a tag factory.
 
-```ts
-const userTag = tag('user')
-const userRelationsTag = tag('user-relations')
-
-const userQuery = query('user', fetchUser, { 
-  tags: [userTag] 
-})
+::: code-group
 
-const userFriendsQuery = query('user-friends', fetchUserFriends, { 
-  tags: [userTag, userRelationsTag] 
-})
-
-const userGroupsQuery = query('user-groups', fetchUserGroups, { 
-  tags: [userTag, userRelationsTag] 
-})
-
-// Update user profile - only invalidate direct user data
-userMutation.mutate(userData, {
-  invalidateTags: [userTag]
-})
+```ts [tags.ts]
+import { tag } from '@kitbag/query'
 
-// Update friend relationship - invalidate user relations
-addFriendMutation.mutate(friendData, {
-  invalidateTags: [userRelationsTag]
-})
+export const catIdTag = tag<Cat, string>(((catId: string) => catId))
 ```
 
-### By Access Patterns
-
-Group by how data is accessed:
-
-```ts
-const listTag = tag('list')       // List views
-const detailTag = tag('detail')   // Detail views
-const searchTag = tag('search')   // Search results
-
-const usersListQuery = query('users-list', fetchUsers, {
-  tags: [userTag, listTag]
-})
+```vue [components/CatViewer.vue]
+<script lang="ts" setup>
+import { useQuery } from '@kitbag/query'
+import { catIdTag } from '../tags'
 
-const userDetailQuery = query('user-detail', fetchUserDetail, {
-  tags: [userTag, detailTag]
-})
+const { catId } = defineProps<{
+  catId: string
+}>()
 
-const userSearchQuery = query('user-search', searchUsers, {
-  tags: [userTag, searchTag]
+const query = useQuery(fetchCat, () => [catId], { 
+  tags: (cat: Cat) => [catIdTag(cat.id)] 
 })
+</script>
 ```
 
-## Best Practices
-
-### 1. Use Descriptive Tag Names
-
-Make tag purposes clear:
-
-```ts
-// ✅ Good
-const userProfileTag = tag('user-profile')
-const dashboardMetricsTag = tag('dashboard-metrics')
-const orderHistoryTag = tag('order-history')
-
-// ❌ Bad
-const tag1 = tag('data1')
-const tag2 = tag('stuff')
-const tag3 = tag('things')
-```
-
-### 2. Don't Over-Tag
-
-Use tags strategically, not on every query:
-
-```ts
-// ✅ Good - Strategic tagging
-const userQuery = query('user', fetchUser, { tags: [userTag] })
-const staticConfigQuery = query('config', fetchConfig) // No tags needed
+```vue [components/CatEditForm.vue]
+<script lang="ts" setup>
+import { refreshQueryData } from '@kitbag/query'
+import { catIdTag } from '../tags'
 
-// ❌ Bad - Over-tagging
-const timestampQuery = query('timestamp', () => Date.now(), { 
-  tags: [timeTag, utilityTag, helperTag] // Unnecessary
-})
-```
-
-### 3. Create a Tag System
-
-Establish consistent tag naming and organization:
-
-```ts
-// tags/index.ts
-export const tags = {
-  // Entities
-  user: tag('user'),
-  post: tag('post'),
-  comment: tag('comment'),
-  
-  // Features  
-  dashboard: tag('dashboard'),
-  settings: tag('settings'),
-  reports: tag('reports'),
-  
-  // Data types
-  list: tag('list'),
-  detail: tag('detail'),
-  search: tag('search')
+function save(catId: string): Promise<void> {
+  ...
+  refreshQueryData(catIdTag(catId))
 }
+</script>
 ```
 
-### 4. Document Tag Relationships
-
-Document how your tags relate to each other:
-
-```ts
-/**
- * Tag Relationships:
- * 
- * userTag: All user-related queries
- *   - userProfileTag: User profile data
- *   - userSettingsTag: User settings
- *   - userActivityTag: User activity/history
- * 
- * postTag: All post-related queries
- *   - postListTag: Post lists/feeds
- *   - postDetailTag: Individual post details
- *   - postMetricsTag: Post analytics
- */
-```
-
-## Performance Considerations
-
-### Tag Granularity
-
-Balance between too broad and too specific:
-
-```ts
-// Too broad - invalidates too much
-const dataTag = tag('data') // Everything uses this
-
-// Too specific - hard to manage
-const userPage1Tag = tag('user-page-1')
-const userPage2Tag = tag('user-page-2')
-// ... hundreds of specific tags
-
-// Just right - meaningful groupings
-const userTag = tag('user')
-const userListTag = tag('user-list')
-const userProfileTag = tag('user-profile')
-```
-
-### Invalidation Frequency
-
-Consider how often you need to invalidate:
-
-```ts
-// High-frequency updates - specific tags
-const liveDataTag = tag('live-data')
-const notificationsTag = tag('notifications')
-
-// Low-frequency updates - broader tags
-const configTag = tag('config')
-const staticContentTag = tag('static-content')
-```
-
-## Next Steps
-
-Learn more about cache management:
-
-- [Caching](/core-concepts/caching) - Understanding cache behavior
-- [useQuery Composable](/composables/useQuery) - Using tags with queries
-- [Advanced Concepts](/advanced-concepts/error-handling) - Advanced cache strategies -->
\ No newline at end of file
+:::

From 65a4cba4971b83209b9238c4e8a3cefea1c1ec7c Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Mon, 20 Oct 2025 20:01:34 -0500
Subject: [PATCH 4/8] code review suggestions

---
 docs/core-concepts/queries.md           | 18 +++----
 docs/core-concepts/tags-invalidation.md | 63 +++++--------------------
 2 files changed, 22 insertions(+), 59 deletions(-)

diff --git a/docs/core-concepts/queries.md b/docs/core-concepts/queries.md
index 4877072..cd3d20e 100644
--- a/docs/core-concepts/queries.md
+++ b/docs/core-concepts/queries.md
@@ -9,7 +9,7 @@ function searchCats(breed?: string) {
   ...
 }
 
-const catsQuery = query(searchCats, () => ['Maine Coon'])
+const catsQuery = query(searchCats, ['Maine Coon'])
 ```
 
 ## Query Properties
@@ -29,7 +29,7 @@ const catsQuery = query(searchCats, () => ['Maine Coon'])
 The query includes `execute`, which can be called at any point to force the function to be called again.
 
 ```ts
-const catsQuery = query(searchCats, () => ['Ragdoll'])
+const catsQuery = query(searchCats, ['Ragdoll'])
 
 function refresh(): void {
   catsQuery.execute()
@@ -45,9 +45,9 @@ Note that if awaiting a query, any errors that occur will be thrown. Consider pl
 :::
 
 ```ts
-const regularQuery = query(searchCats, () => ['Persian'])
+const regularQuery = query(searchCats, ['Persian'])
 //     ^? data: Cat[] | undefined
-const awaitedQuery = await query(searchCats, () => ['Persian'])
+const awaitedQuery = await query(searchCats, ['Persian'])
 //     ^? data: Cat[]
 ```
 
@@ -68,7 +68,7 @@ By default a query that hasn't been executed (or hasn't finished executing) will
 
 ```ts
 const placeholder: Cat[] = []
-const catsQuery = await query(searchCats, () => ['Bengal'], { placeholder })
+const catsQuery = await query(searchCats, ['Bengal'], { placeholder })
 //     ^? data: Cat[]
 ```
 
@@ -77,7 +77,7 @@ const catsQuery = await query(searchCats, () => ['Bengal'], { placeholder })
 Automatically re-trigger the function on an interval. Value provided is time in milliseconds.
 
 ```ts
-const catsQuery = await query(searchCats, () => ['Persian'], { interval: 30_000 })
+const catsQuery = await query(searchCats, ['Persian'], { interval: 30_000 })
 // automatically calls `searchCats` when query is created, and then again every 30 seconds
 ```
 
@@ -86,7 +86,7 @@ const catsQuery = await query(searchCats, () => ['Persian'], { interval: 30_000
 Automatically re-try the function when an error occurs. By default the query will wait `500` milliseconds between retries.
 
 ```ts
-const catsQuery = query(searchCats, () => ['Siamese'], { retries: 3 })
+const catsQuery = query(searchCats, ['Siamese'], { retries: 3 })
 // will try to call `searchCats` a total of 3 times, waiting 500 MS between each attempt
 ```
 
@@ -94,7 +94,7 @@ Alternatively you can pass in `RetryOptions`, which allows you to specify both a
 
 ```ts
 const retries = { count: 1, delay: 1_000 }
-const catsQuery = query(searchCats, () => ['Siamese'], { retries: 3 })
+const catsQuery = query(searchCats, ['Siamese'], { retries: 3 })
 // will retry after 1,000 MS once if initial call fails
 ```
 
@@ -108,7 +108,7 @@ The `useQuery` function adds some super useful, vue specific functionality you'd
 
 ### Parameters argument is reactive
 
-When parameters for your query function change, the query is automatically updated. 
+The parameters for your query must be provided as a getter, which ensures they are reactive. When the parameters change, the query is automatically updated. The old query is disposed and a new query is created.
 
 ```ts
 import { useQuery } from '@kitbag/query'
diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index edfc9f3..522f0d6 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -1,6 +1,6 @@
 # Tags & Invalidation
 
-When it comes time to refresh your query, there are a few options. First, each query has an `execute()` function, which will force the query to refetch and update the reactive `data` for your query but also any other query that shares the same function and arguments.
+When it comes time to refresh your query, there are a few options. First, each query has an `execute()` function which will ensure your query function gets called again.
 
 ## refreshQueryData
 
@@ -21,67 +21,30 @@ function handleRefreshClick(): void {
 
 ## Tags
 
-Often we have multiple queries to different functions that are related to each other. For example, any queries that use the current user token in API headers would probably want to be called again if the token changes. Ideally these queries that are otherwise unrelated could be grouped together.
+Often we have multiple queries to different functions that are related to each other. Ideally these queries that are otherwise unrelated could be grouped together. The group ensures an easy way to set or invalidate the cache for the whole group.
 
-Tags offer a way to not only organize related queries but also to set and invalidate a cache for queries you might not have direct access to. Think of `tag` as a function that generates a unique identifier that helps Kitbag Query to find the query later.
+As an example, let's group some queries that all use the same external API. That way when the API version changes, we can update all the queries at once because they share the same tag.
 
-Since each tag generated is unique, we recommend creating and exporting your tags from a shared location.
-
-::: code-group
-
-```ts [tags.ts]
-import { tag } from '@kitbag/query'
-
-export const requiresUserContext = tag()
-```
-
-:::
-
-Then from wherever queries are created the query options include `tags`, which expects an array of tags.
-
-::: code-group
-
-```vue [components/UserProfile.ts]
+```vue
 <script lang="ts" setup>
-import { useQuery } from '@kitbag/query'
-import { requiresUserContext } from '../tags'
-import { fetchMe } from '../services/userApi'
+import { tag, useQuery, refreshQueryData } from '@kitbag/query'
 
-const meQuery = useQuery(fetchMe, () => [], { tags: [requiresUserContext] })
-</script>
-```
+const usesCatsApi = tag()
 
-```vue [components/NotificationsIndicator.ts]
-<script lang="ts" setup>
-import { useQuery } from '@kitbag/query'
-import { requiresUserContext } from '../tags'
-import { getNotifications } from '../services/notificationsApi'
+const catNamesQuery = useQuery(randomCatNames, () => [...], { tags: [usesCatsApi] })
+const catYearsQuery = useQuery(convertToCatYears, () => [...], { tags: [usesCatsApi] })
+const catYearsQuery = useQuery(checkCatIsNapping, () => [...], { tags: [usesCatsApi] })
 
-const notificationsQuery = useQuery(getNotifications, () => [], { tags: [requiresUserContext] })
+// later
+refreshQueryData(usesCatsApi)
 </script>
 ```
 
-:::
-
-Then later perhaps when the user token changes, you can access and invalidate the cache for this tag.
-
-::: code-group
-
-```ts [services/auth.ts]
-import { refreshQueryData } from '@kitbag/query'
-import { requiresUserContext } from '../tags'
-
-function onLoginSuccessful(): void {
-  // refreshes both meQuery and notificationsQuery
-  refreshQueryData(requiresUserContext)
-}
-```
-
-:::
+Think of `tag` as a function that generates a unique identifier that helps Kitbag Query to find the query later. Since each tag generated is unique, we recommend creating and exporting your tags from a shared location.
 
 ## Tag Type
 
-Kitbag Query also tracks a generic on each tag, which By default is `unknown`. This satisfies any query, but assigning your actual type not only validates the query type but also provides improved type safety later when accessing cached data, like in `setQueryData`
+Kitbag Query also supports typed tags. Where a generic type can be added to a tag for extra type safety. By default the tag type is `unknown`. This satisfies any query, but assigning your actual type not only validates the query type but also provides improved type safety later when accessing cached data, like in `setQueryData`.
 
 ```ts
 import { tag, setQueryData } from '@kitbag/query'

From 6162085f74590d69b3deb08c3588902b93ec333a Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Wed, 22 Oct 2025 20:19:39 -0500
Subject: [PATCH 5/8] Update docs/core-concepts/tags-invalidation.md

Co-authored-by: Craig Harshbarger <pleek91@gmail.com>
---
 docs/core-concepts/tags-invalidation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index 522f0d6..a6e3260 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -21,7 +21,7 @@ function handleRefreshClick(): void {
 
 ## Tags
 
-Often we have multiple queries to different functions that are related to each other. Ideally these queries that are otherwise unrelated could be grouped together. The group ensures an easy way to set or invalidate the cache for the whole group.
+Often we have multiple queries to different functions that are related to each other. These queries that are otherwise unrelated could be grouped together. The group ensures an easy way to set or invalidate the cache for the whole group.
 
 As an example, let's group some queries that all use the same external API. That way when the API version changes, we can update all the queries at once because they share the same tag.
 

From a26edef60df6040a9f80b004c35c36b0507da220 Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Wed, 22 Oct 2025 21:04:58 -0500
Subject: [PATCH 6/8] code review suggestions

---
 docs/core-concepts/tags-invalidation.md | 60 ++++---------------------
 1 file changed, 9 insertions(+), 51 deletions(-)

diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index a6e3260..9c70a73 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -23,20 +23,18 @@ function handleRefreshClick(): void {
 
 Often we have multiple queries to different functions that are related to each other. These queries that are otherwise unrelated could be grouped together. The group ensures an easy way to set or invalidate the cache for the whole group.
 
-As an example, let's group some queries that all use the same external API. That way when the API version changes, we can update all the queries at once because they share the same tag.
-
 ```vue
 <script lang="ts" setup>
 import { tag, useQuery, refreshQueryData } from '@kitbag/query'
 
-const usesCatsApi = tag()
+const catsTag = tag()
 
-const catNamesQuery = useQuery(randomCatNames, () => [...], { tags: [usesCatsApi] })
-const catYearsQuery = useQuery(convertToCatYears, () => [...], { tags: [usesCatsApi] })
-const catYearsQuery = useQuery(checkCatIsNapping, () => [...], { tags: [usesCatsApi] })
+const catNamesQuery = useQuery(randomCatNames, () => [...], { tags: [catsTag] })
+const catYearsQuery = useQuery(convertToCatYears, () => [...], { tags: [catsTag] })
+const catNappingQuery = useQuery(checkCatIsNapping, () => [...], { tags: [catsTag] })
 
 // later
-refreshQueryData(usesCatsApi)
+refreshQueryData(catsTag)
 </script>
 ```
 
@@ -57,59 +55,19 @@ setQueryData(catTag, (data) => ...)
 
 ## Tag Factories
 
-Tags can also be configured as factories, which offer a way to increase specificity through a callback you define. For example, if you have a bunch of instances of a component that has a query and you want to selectively invalidate cache.
-
-::: code-group
-
-```vue [components/CatViewer.vue]
-<script lang="ts" setup>
-import { useQuery } from '@kitbag/query'
-
-const { catId } = defineProps<{
-  catId: string
-}>()
-
-const query = useQuery(fetchCat, () => [catId])
-</script>
-```
-
-:::
+Tags can also be configured as factories, which offer a way to increase specificity through a callback you define.
 
-If in another part of your application you update the cat model, you could instead define a tag factory.
-
-::: code-group
-
-```ts [tags.ts]
+```ts
 import { tag } from '@kitbag/query'
 
 export const catIdTag = tag<Cat, string>(((catId: string) => catId))
 ```
 
-```vue [components/CatViewer.vue]
-<script lang="ts" setup>
-import { useQuery } from '@kitbag/query'
-import { catIdTag } from '../tags'
-
-const { catId } = defineProps<{
-  catId: string
-}>()
-
-const query = useQuery(fetchCat, () => [catId], { 
-  tags: (cat: Cat) => [catIdTag(cat.id)] 
-})
-</script>
-```
-
-```vue [components/CatEditForm.vue]
-<script lang="ts" setup>
-import { refreshQueryData } from '@kitbag/query'
-import { catIdTag } from '../tags'
+This ensures that the tag is narrowed to only the queries for _this_ `catId`.
 
+```ts
 function save(catId: string): Promise<void> {
   ...
   refreshQueryData(catIdTag(catId))
 }
-</script>
 ```
-
-:::

From 2750e581a5528153b2e7e7b9d35f403c9bf0bc92 Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Fri, 24 Oct 2025 13:47:32 -0500
Subject: [PATCH 7/8] Update docs/core-concepts/tags-invalidation.md

Co-authored-by: Craig Harshbarger <craig.harshbarger@perplexity.ai>
---
 docs/core-concepts/tags-invalidation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index 9c70a73..58de977 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -21,7 +21,7 @@ function handleRefreshClick(): void {
 
 ## Tags
 
-Often we have multiple queries to different functions that are related to each other. These queries that are otherwise unrelated could be grouped together. The group ensures an easy way to set or invalidate the cache for the whole group.
+Often we have multiple queries to different functions that are related to each other. These queries could be grouped together using a tag. The tag ensures an easy way to set or invalidate the cache for the whole group.
 
 ```vue
 <script lang="ts" setup>

From 98dce67071d149e1e9868b4873ad4b0514f0b041 Mon Sep 17 00:00:00 2001
From: Evan Sutherland <stackoverfloweth@gmail.com>
Date: Fri, 24 Oct 2025 14:01:52 -0500
Subject: [PATCH 8/8] code review suggestions

---
 docs/core-concepts/tags-invalidation.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/core-concepts/tags-invalidation.md b/docs/core-concepts/tags-invalidation.md
index 58de977..ef69ffe 100644
--- a/docs/core-concepts/tags-invalidation.md
+++ b/docs/core-concepts/tags-invalidation.md
@@ -15,7 +15,7 @@ function handleRefreshClick(): void {
   refreshQueryData(searchCats)
 
   // invalidates only queries that call searchCats with ['Himalayan']
-  refreshQueryData(searchCats, () => ['Himalayan'])
+  refreshQueryData(searchCats, ['Himalayan'])
 }
 ```
 
@@ -63,6 +63,12 @@ import { tag } from '@kitbag/query'
 export const catIdTag = tag<Cat, string>(((catId: string) => catId))
 ```
 
+Then assign tags on queries using the tags getter syntax.
+
+```ts
+const catsQuery = useQuery(getCat, () => [props.catId], { tags: (cat) => [catIdTag(cat.id)] })
+```
+
 This ensures that the tag is narrowed to only the queries for _this_ `catId`.
 
 ```ts