Polish:

 - Terminology consistent with docs
 - Slight tweaks to messaging
 - README improvements
 - Center the SQLite File Inspector content on the page
 - Fix issue with hover color for link in tooltip

Author: Conrad Hofmeyr

tools/diagnostics-app/README.md

@@ -1,12 +1,10 @@
 # Sync Diagnostics Client
 
-A browser-based tool for inspecting PowerSync databases. Both live (via sync) and offline (via SQLite file upload).
+A browser-based tool for inspecting PowerSync sync behavior and databases. Supports both live syncing from a PowerSync instance, and offline inspection of a SQLite database (by uploading a file).
 
-The app is available at [https://diagnostics-app.powersync.com/](https://diagnostics-app.powersync.com/)
+A hosted version of the Sync Diagnostics Client is available at [https://diagnostics-app.powersync.com/](https://diagnostics-app.powersync.com/). It can also be run as a local standalone web app. It is based on the [PowerSync Web SDK](/packages/web/).
 
-It can also be run as a local standalone web app, and is based on the [web SDK](/packages/web/).
-
-## Running the App
+## Running the Sync Diagnostics Client
 
 ### Docker
 
@@ -18,7 +16,7 @@ The app will be available on http://localhost:8082.
 
 ### Local Development
 
-In the root of the repository, run:
+In the **root of the repository**, run:
 
 ```sh
 pnpm install
@@ -39,8 +37,8 @@ The landing page offers two paths:
 
 ![](public/images/landing-page.png)
 
-- **Connect to PowerSync**: Live sync diagnostics using a JWT token. View real-time sync status, bucket data, and manage client parameters.
-- **Inspect SQLite File**: Offline inspection of a local `SQLite` file. No authentication required.
+- **Connect to PowerSync**: Live sync diagnostics using a JWT token. View real-time sync status, bucket data, and manage connection/client parameters.
+- **Inspect SQLite File**: Offline inspection of a local SQLite database file. No authentication required.
 
 ---
 
@@ -77,10 +75,10 @@ The main dashboard after connecting:
 
 ![](public/images/sync-streams.png)
 
-Manage sync stream subscriptions directly from the Sync Overview page:
+Manage Sync Stream subscriptions directly from the _Sync Overview_ page:
 
-- View all active stream subscriptions with their parameters, priority, sync time, and eviction time.
-- **Add Subscription**: Subscribe to a new stream with optional parameters and priority.
+- View all active Sync Stream subscriptions with their parameters, priority, sync time, and eviction time.
+- **Add Subscription**: Subscribe to a new Sync Stream with optional subscription parameters and priority.
 - **Unsubscribe**: Remove explicit subscriptions (triggers a reconnect to apply the change).
 
 ### SQL Console
@@ -99,13 +97,13 @@ Execute read-only SQL queries against the live PowerSync database:
 
 The schema is dynamically inferred from downloaded data and automatically updated as new data arrives. This page displays the current inferred schema for reference.
 
-Note: Tables with 0 synced rows won't appear in the schema. To refresh after sync rule/stream changes, use "Clear & Redownload" on the Sync Overview page.
+Note: Tables with 0 synced rows won't appear in the schema. To refresh after Sync Streams / Sync Rules changes, use "Clear & Redownload" on the _Sync Overview_ page.
 
-### Client Parameters
+### Connection Parameters / Client Parameters
 
 ![](public/images/client-parameters.png)
 
-Manage client parameters that are sent with sync requests:
+Manage [Connection Parameters](https://docs.powersync.com/sync/streams/parameters#connection-parameters) (Sync Streams) / [Client Parameters](https://docs.powersync.com/sync/rules/client-parameters) (Sync Rules) that are sent with sync requests:
 
 - Add, edit, and delete key-value parameters.
 - Supports string, number, boolean, array, and object types.
@@ -115,13 +113,13 @@ Manage client parameters that are sent with sync requests:
 
 ## SQLite File Inspector
 
-The File Inspector allows offline inspection of SQLite database files. It is useful for post-mortem analysis of database files extracted from devices. No authentication is required.
+The File Inspector allows offline inspection of SQLite database files. It is useful for analysis of database files extracted from devices. No authentication is required.
 
 ### Opening a File
 
 ![](public/images/inspector-drop-zone.png)
 
-Drag and drop a `SQLite` file, or click to browse. The file is opened in-browser using wa-sqlite - nothing is uploaded to a server.
+Drag and drop a SQLite database file, or click to browse. The file is opened in-browser using `wa-sqlite` - nothing is uploaded to a server.
 
 ### Database Overview
 
@@ -135,7 +133,7 @@ Drag and drop a `SQLite` file, or click to browse. The file is opened in-browser
 
 ![](public/images/inspector-sql-console.png)
 
-Execute read-only SQL queries against the uploaded file. Works the same as the sync SQL console, with separate query history.
+Execute read-only SQL queries against the uploaded file. Works the same as the _SQL Console_ for live synced databases, with separate query history.
 
 ---
 

tools/diagnostics-app/src/app/views/client-params.tsx

@@ -150,12 +150,12 @@ function ClientParamsContent() {
   };
 
   return (
-    <NavigationPage title="Client Parameters">
+    <NavigationPage title="Connection/Client Parameters">
       <div className="min-w-0 max-w-full overflow-x-hidden p-6">
         <Card>
           <CardHeader>
-            <CardTitle className="text-xl">Parameters</CardTitle>
-            <CardDescription>Configure key-value parameters that will be sent with sync requests.</CardDescription>
+            <CardTitle className="text-xl">Connection Parameters / Client Parameters</CardTitle>
+            <CardDescription>Configure key-value Connection Parameters (Sync Streams) / Client Parameters (Sync Rules) that will be sent with sync requests.</CardDescription>
           </CardHeader>
           <CardContent className="space-y-4">
             {(storedParams ?? []).length === 0 ? (

tools/diagnostics-app/src/app/views/sync-diagnostics.tsx

@@ -295,15 +295,23 @@ export default function SyncDiagnosticsPage() {
                         </span>
                       </TooltipTrigger>
                       <TooltipContent className="max-w-92">
-                        Two separate limits apply (both PSYNC_S2305, default {DEFAULT_SYNC_LIMIT.toLocaleString()}{' '}
-                        each): <strong>bucket count</strong> and <strong>parameter query results</strong>.
+                        Two separate limits apply: <strong>bucket count</strong> and <strong>parameter query results</strong>. 
+                        Both yield a PSYNC_S2305 error when exceeded. Both <a
+                            href="https://docs.powersync.com/debugging/troubleshooting#too-many-buckets-psync_s2305"
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="underline hover:text-primary-foreground/80"
+                          >
+                            default
+                          </a>{' '}
+                          to a limit of {DEFAULT_SYNC_LIMIT.toLocaleString()}.
                         <div className="mt-2">
                           Global buckets count only toward bucket count. Parameter query buckets (in either{' '}
                           <a
                             href="https://docs.powersync.com/sync/rules/parameter-queries"
                             target="_blank"
                             rel="noopener noreferrer"
-                            className="underline hover:text-foreground"
+                            className="underline hover:text-primary-foreground/80"
                           >
                             Sync Rules
                           </a>{' '}
@@ -312,12 +320,12 @@ export default function SyncDiagnosticsPage() {
                             href="https://docs.powersync.com/sync/streams/parameters"
                             target="_blank"
                             rel="noopener noreferrer"
-                            className="underline hover:text-foreground"
+                            className="underline hover:text-primary-foreground/80"
                           >
                             Sync Streams
                           </a>
-                          ) count toward both, but are de-duplicated client-side, so the server's parameter result count
-                          may be higher.
+                          ) count toward both, but are de-duplicated client-side, so the parameter result count 
+                          on the PowerSync Service side may be higher.
                         </div>
                       </TooltipContent>
                     </Tooltip>
@@ -516,10 +524,10 @@ export default function SyncDiagnosticsPage() {
                 <span className={cn('font-medium', totals.buckets >= 900 ? 'text-destructive' : 'text-amber-600')}>
                   {totals.buckets >= 900 ? 'Critical: ' : 'Warning: '}
                 </span>
-                {totals.buckets.toLocaleString()} of {DEFAULT_SYNC_LIMIT.toLocaleString()} buckets used (PSYNC_S2305,
-                default limit). {totals.parameterized_buckets.toLocaleString()} are parameterized - at least that many
-                parameter query results on the server. Review your Sync Config to reduce buckets and parameter query
-                results for this user.{' '}
+                {totals.buckets.toLocaleString()} buckets used (PSYNC_S2305, default limit of {DEFAULT_SYNC_LIMIT.toLocaleString()} unless specifically
+                configured higher for your instance). {totals.parameterized_buckets.toLocaleString()} are parameterized - at least that many
+                parameter query results on the server. Depending on your configuration ({DEFAULT_SYNC_LIMIT.toLocaleString()} is the default limit), you may
+                need to adjust your Sync Config to reduce the numbe rof buckets and parameter query results for this user.{' '}
                 <a
                   href="https://docs.powersync.com/debugging/troubleshooting#too-many-buckets-psync_s2305"
                   target="_blank"

tools/diagnostics-app/src/components/widgets/FileDropZone.tsx

@@ -84,7 +84,7 @@ export function FileDropZone({ onFileSelected, isLoading, error }: FileDropZoneP
   const displayError = validationError || error;
 
   return (
-    <div className="fixed inset-0 flex flex-col items-center justify-center p-6 overflow-hidden">
+    <div className="flex min-h-full flex-col items-center justify-center p-6">
       <div className="w-full max-w-2xl space-y-5">
         {/* Logo & title */}
         <div className="flex flex-col items-center gap-2">

tools/diagnostics-app/src/components/widgets/NewStreamSubscription.tsx

@@ -77,15 +77,15 @@ export function NewStreamSubscription(props: { open: boolean; close: () => void
           {({ values, errors, handleChange, handleBlur, isSubmitting, handleSubmit, setFieldValue }) => (
             <form onSubmit={handleSubmit}>
               <DialogHeader>
-                <DialogTitle>Subscribe to sync stream</DialogTitle>
+                <DialogTitle>Subscribe to Sync Stream</DialogTitle>
                 <DialogDescription>
-                  Add a stream subscription with optional parameters and priority override.
+                  Add a Sync Stream subscription with optional subscription parameters and priority override.
                 </DialogDescription>
               </DialogHeader>
               <div className="grid gap-4 py-4">
                 <div className="grid grid-cols-3 gap-3">
                   <div className="col-span-2">
-                    <Label htmlFor="stream-name">Stream name</Label>
+                    <Label htmlFor="stream-name">Sync Stream name</Label>
                     <Input
                       id="stream-name"
                       autoFocus
@@ -119,7 +119,7 @@ export function NewStreamSubscription(props: { open: boolean; close: () => void
                   </div>
                 </div>
                 <div>
-                  <Label>Parameters (JSON)</Label>
+                  <Label>Subscription Parameters (JSON)</Label>
                   <div
                     className={cn(
                       'mt-1.5 rounded-md border overflow-hidden relative',

tools/diagnostics-app/src/routes/_authenticated.tsx

@@ -57,7 +57,7 @@ const NAVIGATION_ITEMS = [
   { path: '/sync-diagnostics', title: 'Sync Overview', icon: Table2 },
   { path: '/schema', title: 'Dynamic Schema', icon: Database },
   { path: '/sql-console', title: 'SQL Console', icon: Terminal },
-  { path: '/client-parameters', title: 'Client Parameters', icon: SlidersHorizontal },
+  { path: '/client-parameters', title: 'Connection Parameters', icon: SlidersHorizontal },
   { path: '/file-inspector', title: 'File Inspector', icon: FileSearch }
 ];