From 17783ccadcf52b450a4561e9e3b53ae19e42d583 Mon Sep 17 00:00:00 2001
From: Dipak Halkude <dipakdh12345@gmail.com>
Date: Wed, 15 Oct 2025 15:16:30 +0530
Subject: [PATCH 1/5] docs: unify query update terminology and improve
 navigation

---
 .../docs/20-core-concepts/60-remote-functions.md   | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
index 969b90d17121..c46194a38f52 100644
--- a/documentation/docs/20-core-concepts/60-remote-functions.md
+++ b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -160,9 +160,9 @@ export const getPost = query(v.string(), async (slug) => {
 
 Both the argument and the return value are serialized with [devalue](https://github.com/sveltejs/devalue), which handles types like `Date` and `Map` (and custom types defined in your [transport hook](hooks#Universal-hooks-transport)) in addition to JSON.
 
-### Refreshing queries
+### Updating queries
 
-Any query can be re-fetched via its `refresh` method, which retrieves the latest value from the server:
+Any query can be updated via its `refresh` method, which retrieves the latest value from the server:
 
 ```svelte
 <button onclick={() => getPosts().refresh()}>
@@ -172,6 +172,8 @@ Any query can be re-fetched via its `refresh` method, which retrieves the latest
 
 > [!NOTE] Queries are cached while they're on the page, meaning `getPosts() === getPosts()`. This means you don't need a reference like `const posts = getPosts()` in order to update the query.
 
+> [!NOTE] For more advanced update patterns including optimistic updates, see the [command](#command) section.
+
 ## query.batch
 
 `query.batch` works like `query` except that it batches requests that happen within the same macrotask. This solves the so-called n+1 problem: rather than each query resulting in a separate database call (for example), simultaneous queries are grouped together.
@@ -616,7 +618,7 @@ You can prevent sensitive data (such as passwords and credit card numbers) from
 
 In this example, if the data does not validate, only the first `<input>` will be populated when the page reloads.
 
-### Single-flight mutations
+### Updating queries after form submissions
 
 By default, all queries used on the page (along with any `load` functions) are automatically refreshed following a successful form submission. This ensures that everything is up-to-date, but it's also inefficient: many queries will be unchanged, and it requires a second trip to the server to get the updated data.
 
@@ -662,6 +664,8 @@ export const updatePost = form(
 );
 ```
 
+> [!NOTE] For basic query updates, see the [query](#query) section. For programmatic updates outside of forms, see the [command](#command) section.
+
 The second is to drive the single-flight mutation from the client, which we'll see in the section on [`enhance`](#form-enhance).
 
 ### Returns and redirects
@@ -761,7 +765,7 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 The callback receives the `form` element, the `data` it contains, and a `submit` function.
 
-To enable client-driven [single-flight mutations](#form-Single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
+To enable client-driven [query updates after form submissions](#form-Single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
 
 ```ts
 import type { RemoteQuery, RemoteQueryOverride } from '@sveltejs/kit';
@@ -988,6 +992,8 @@ try {
 }
 ```
 
+> [!NOTE] This section covers programmatic query updates. For updates triggered by user interactions, see the [form](#form) section. For basic refresh patterns, see the [query](#query) section.
+
 ## prerender
 
 The `prerender` function is similar to `query`, except that it will be invoked at build time to prerender the result. Use this for data that changes at most once per redeployment.

From e0422c6aae2d5a20d5560f902c1a30308bc7892a Mon Sep 17 00:00:00 2001
From: Dipak Halkude <dipakdh12345@gmail.com>
Date: Thu, 16 Oct 2025 21:25:30 +0530
Subject: [PATCH 2/5] docs: unify query update terminology and improve
 navigation

- Fix broken anchor link from #form-Single-flight-mutations to #single-flight-mutations
- Improve documentation consistency and navigation
---
 documentation/docs/20-core-concepts/60-remote-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
index c46194a38f52..7b7b58c5eefe 100644
--- a/documentation/docs/20-core-concepts/60-remote-functions.md
+++ b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -765,7 +765,7 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 The callback receives the `form` element, the `data` it contains, and a `submit` function.
 
-To enable client-driven [query updates after form submissions](#form-Single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
+To enable client-driven [query updates after form submissions](#single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
 
 ```ts
 import type { RemoteQuery, RemoteQueryOverride } from '@sveltejs/kit';

From 389ce47074fc8dd69dab741a7aad5bcf5193f2a1 Mon Sep 17 00:00:00 2001
From: DipakHalkude <128908555+DipakHalkude@users.noreply.github.com>
Date: Thu, 16 Oct 2025 21:32:34 +0530
Subject: [PATCH 3/5] fix: correct broken anchor link in remote functions docs

---
 documentation/docs/20-core-concepts/60-remote-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
index c46194a38f52..7b7b58c5eefe 100644
--- a/documentation/docs/20-core-concepts/60-remote-functions.md
+++ b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -765,7 +765,7 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 The callback receives the `form` element, the `data` it contains, and a `submit` function.
 
-To enable client-driven [query updates after form submissions](#form-Single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
+To enable client-driven [query updates after form submissions](#single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
 
 ```ts
 import type { RemoteQuery, RemoteQueryOverride } from '@sveltejs/kit';

From f74ab2083e7ca96926b3b0bc97caca363ecb4025 Mon Sep 17 00:00:00 2001
From: DipakHalkude <128908555+DipakHalkude@users.noreply.github.com>
Date: Thu, 16 Oct 2025 23:17:28 +0530
Subject: [PATCH 4/5] Fix link reference for query updates section

---
 documentation/docs/20-core-concepts/60-remote-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
index 7b7b58c5eefe..8889c776da3c 100644
--- a/documentation/docs/20-core-concepts/60-remote-functions.md
+++ b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -765,7 +765,7 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 The callback receives the `form` element, the `data` it contains, and a `submit` function.
 
-To enable client-driven [query updates after form submissions](#single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
+To enable client-driven [query updates after form submissions](#updating-queries-after-form-submissions), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
 
 ```ts
 import type { RemoteQuery, RemoteQueryOverride } from '@sveltejs/kit';

From 3a08805d3d5c05e20d45b8f0ffc340867857f8a8 Mon Sep 17 00:00:00 2001
From: Dipak Halkude <dipakdh12345@gmail.com>
Date: Mon, 20 Oct 2025 10:59:51 +0530
Subject: [PATCH 5/5] fix: correct broken anchor link in remote functions docs

---
 documentation/docs/20-core-concepts/60-remote-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
index 7b7b58c5eefe..8889c776da3c 100644
--- a/documentation/docs/20-core-concepts/60-remote-functions.md
+++ b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -765,7 +765,7 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 The callback receives the `form` element, the `data` it contains, and a `submit` function.
 
-To enable client-driven [query updates after form submissions](#single-flight-mutations), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
+To enable client-driven [query updates after form submissions](#updating-queries-after-form-submissions), use `submit().updates(...)`. For example, if the `getPosts()` query was used on this page, we could refresh it like so:
 
 ```ts
 import type { RemoteQuery, RemoteQueryOverride } from '@sveltejs/kit';