docs(site): improve command descriptions

Author: JamieMason

site/src/content/docs/command/fix.mdx

@@ -6,6 +6,7 @@ import { Badge } from "@astrojs/starlight/components";
 import ConfigOption from "@partials/option/config.mdx";
 import DependenciesOption from "@partials/option/dependencies.mdx";
 import DependencyTypesOption from "@partials/option/dependency-types.mdx";
+import DryRunOption from "@partials/option/dry-run.mdx";
 import HelpOption from "@partials/option/help.mdx";
 import LogLevelsOption from "@partials/option/log-levels.mdx";
 import NoAnsiOption from "@partials/option/no-ansi.mdx";
@@ -16,17 +17,21 @@ import SpecifierTypesOption from "@partials/option/specifier-types.mdx";
 
 import QuoteFilters from "@partials/tips/quote-filters.mdx";
 
-Fix every autofixable issue found by `syncpack lint`.
+Fix version mismatches in your monorepo. When the same dependency has different versions across packages, `fix` updates them to match your configuration rules. Use this to resolve issues reported by `lint`. Does not fix formatting—use `format` for that.
 
 ## Examples
 
 ```bash
-# Only fix issues in dependencies and devDependencies
+# Preview changes without modifying files
+syncpack fix --dry-run
+# Fix only dependencies and devDependencies (exclude peer, optional)
 syncpack fix --dependency-types prod,dev
-# Only fix inconsistencies with exact versions (eg "1.2.3")
+# Fix inconsistencies with exact versions only (eg "1.2.3", not "^1.2.3")
 syncpack fix --specifier-types exact
-# Only fix issues in "react" specifically
+# Fix issues in "react" across all packages
 syncpack fix --dependencies react
+# Fix scoped packages like @types/* but exclude others
+syncpack fix --dependencies '@types/**'
 # See more examples
 syncpack fix --help
 # See a short summary of options
@@ -49,6 +54,10 @@ syncpack fix -h
 
 <DependencyTypesOption command="fix" />
 
+### --dry-run
+
+<DryRunOption command="fix" />
+
 ### --log-levels <Badge text="<comma-separated-log-level-names>" />
 
 <LogLevelsOption command="fix" />

site/src/content/docs/command/format.mdx

@@ -12,7 +12,7 @@ import NoAnsiOption from "@partials/option/no-ansi.mdx";
 import QuoteFilters from "@partials/tips/quote-filters.mdx";
 import SourceOption from "@partials/option/source.mdx";
 
-Sort package.json fields into a predictable order and nested fields alphabetically.
+Format package.json files in your monorepo. Sorts fields into consistent order and alphabetises nested fields. Use this to maintain readable, diff-friendly package.json files. Does not change version numbers—use `fix` for that.
 
 ## Examples
 

site/src/content/docs/command/json.mdx

@@ -17,11 +17,7 @@ import SpecifierTypesOption from "@partials/option/specifier-types.mdx";
 
 import QuoteFilters from "@partials/tips/quote-filters.mdx";
 
-Output the state of every instance of every dependency as a JSON object, one per line. This command is best used with tools like [`jq`](https://jqlang.org/) for filtering and processing.
-
-## TypeScript
-
-Each instance printed by `syncpack json` has the type [`JsonOutput`](https://github.com/JamieMason/syncpack/blob/main/npm/syncpack.ts).
+Export dependency data from your monorepo as JSON. Outputs one line per dependency instance with version, location, and status information. Use with tools like [`jq`](https://jqlang.org/) to analyse, filter, or pipe into other commands.
 
 ## Examples
 
@@ -38,6 +34,33 @@ syncpack json --help
 syncpack json -h
 ```
 
+## TypeScript
+
+Each instance printed by `syncpack json` has the type [`JsonOutput`](https://github.com/JamieMason/syncpack/blob/main/npm/syncpack.ts).
+
+```ts
+/** Each Instance printed by `syncpack json` */
+export type JsonOutput = {
+  dependency: string;
+  dependencyGroup: string;
+  dependencyType: DependencyType;
+  package: string;
+  property: ["dependencies"];
+  strategy: CustomType.Any["strategy"];
+  versionGroup: VersionGroupVariant;
+  preferredSemverRange: SemverRange | null;
+  statusCode: StatusCode;
+  actual: {
+    raw: string;
+    type: SpecifierType;
+  };
+  expected: {
+    raw: string;
+    type: SpecifierType;
+  } | null;
+};
+```
+
 ## Options
 
 <QuoteFilters />

site/src/content/docs/command/lint.mdx

@@ -15,7 +15,7 @@ import SortOption from "@partials/option/sort.mdx";
 import SourceOption from "@partials/option/source.mdx";
 import SpecifierTypesOption from "@partials/option/specifier-types.mdx";
 
-Lint all versions and ranges and exit with 0 or 1 based on whether all files match your Syncpack configuration file.
+Check for version mismatches in your monorepo. Reports dependencies that don't match your configuration rules and exits with status code 1 if issues are found. Use `fix` to resolve reported issues. Does not check formatting—use `format --check` for that.
 
 ## Examples
 

site/src/content/docs/command/list.mdx

@@ -15,7 +15,7 @@ import SortOption from "@partials/option/sort.mdx";
 import SourceOption from "@partials/option/source.mdx";
 import SpecifierTypesOption from "@partials/option/specifier-types.mdx";
 
-Query and inspect all dependencies in your project, both valid and invalid.
+List all dependencies in your monorepo with their versions and locations. Shows which dependencies have mismatches, are ignored, or follow your rules. Use this to explore what's installed before running `lint` or `fix`.
 
 ## Examples
 

site/src/content/docs/command/update.mdx

@@ -18,7 +18,7 @@ import SourceOption from "@partials/option/source.mdx";
 import SpecifierTypesOption from "@partials/option/specifier-types.mdx";
 import TargetOption from "@partials/option/target.mdx";
 
-Update to the latest versions on the npm registry.
+Update dependencies in your monorepo to newer versions from the npm registry. Checks for available updates and modifies package.json files to use them. Unlike `fix` which synchronises versions across packages, `update` fetches the latest published versions. Use `--target` to control update strategy (latest, minor, patch).
 
 ## Examples