From 84c4887718299fcca64086e4fab7f54d39f6f56c Mon Sep 17 00:00:00 2001
From: Bohdan Pomohaibo <b.pomohaibo@gmail.com>
Date: Fri, 20 Feb 2026 20:09:58 +0200
Subject: [PATCH 1/2] docs(linter): document plugin rewrite fix behavior

---
 src/content/docs/linter/plugins.mdx   | 36 +++++++++++++++++++++++----
 src/content/docs/reference/gritql.mdx |  4 +++
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/linter/plugins.mdx b/src/content/docs/linter/plugins.mdx
index 909c66c00..bfb05625c 100644
--- a/src/content/docs/linter/plugins.mdx
+++ b/src/content/docs/linter/plugins.mdx
@@ -3,9 +3,9 @@ title: Linter Plugins
 description: An overview of how to use Biome's Linter Plugins
 ---
 
-Biome Linter supports [GritQL](/reference/gritql/) plugins. Currently, these
-plugins allow you to match specific code patterns and register customized
-diagnostic messages for them.
+Biome Linter supports [GritQL](/reference/gritql/) plugins. Plugins can match
+specific code patterns, report customized diagnostics, and suggest fixable
+rewrites.
 
 Here is an example of a plugin that reports on all usages of `Object.assign()`:
 
@@ -46,6 +46,29 @@ $ biome lint
     14 │ }
 ```
 
+Plugins can also suggest code rewrites using the `=>` operator:
+
+```grit
+language js
+
+`console.log($msg)` as $call where {
+    register_diagnostic(
+        span = $call,
+        message = "Use console.info instead of console.log.",
+        severity = "warn",
+        fix_kind = "safe"
+    ),
+    $call => `console.info($msg)`
+}
+```
+
+Rewrite behavior:
+
+- Without `--write`, rewrites are shown as suggestions but not applied.
+- With `--write`, Biome applies plugin rewrites marked with `fix_kind = "safe"`.
+- With `--write --unsafe`, Biome also applies unsafe plugin rewrites.
+- If `fix_kind` is omitted, the rewrite is treated as unsafe by default.
+
 ## Target Languages
 
 A GritQL snippet always attempts to match against a given _target language_.
@@ -69,7 +92,7 @@ language css;
 }
 ```
 
-We currently do not support other target languages than JavaScript and CSS.
+Biome currently supports JavaScript, CSS, and JSON target languages.
 
 ## Plugin API
 
@@ -81,10 +104,13 @@ Biome currently supports one extra function:
 
 Registers a diagnostic to be reported whenever the pattern matches.
 
-Supports three arguments:
+Supports four arguments:
 
 - `span` (required): The syntax node to attach the diagnostic to. This is
   typically a variable that you matched within a code snippet.
 - `message` (required): The message to show with the diagnostic.
 - `severity`: The severity of the diagnostic. Allowed values are: `hint`,
   `info`, `warn`, and `error`. By default, `error` is used.
+- `fix_kind`: Safety of an associated rewrite fix (`safe` or `unsafe`). This is
+  only relevant when the pattern also uses the rewrite operator (`=>`). By
+  default, fixes are treated as unsafe.
diff --git a/src/content/docs/reference/gritql.mdx b/src/content/docs/reference/gritql.mdx
index 151a2f043..dad1e4914 100644
--- a/src/content/docs/reference/gritql.mdx
+++ b/src/content/docs/reference/gritql.mdx
@@ -25,6 +25,10 @@ Biome uses GritQL for two purposes:
 - The [`biome search`](/reference/cli/#biome-search) command, which we hope to
   extend to our IDE extensions as well.
 
+When GritQL is used in analyzer plugins, patterns can also include rewrites
+(`=>`) to provide fixable diagnostics. See [Linter Plugins](/linter/plugins)
+for details about safe vs unsafe fixes and `fix_kind`.
+
 ## Patterns
 
 GritQL queries work through _patterns_. The most common pattern you will see is

From ee660fce0bf3c49806f221205dc24ad269ad790d Mon Sep 17 00:00:00 2001
From: Bohdan Pomohaibo <b.pomohaibo@gmail.com>
Date: Mon, 23 Feb 2026 19:16:47 +0200
Subject: [PATCH 2/2] docs(linter): remove redundant language directive from
 plugin example

---
 src/content/docs/linter/plugins.mdx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/content/docs/linter/plugins.mdx b/src/content/docs/linter/plugins.mdx
index bfb05625c..b942a14db 100644
--- a/src/content/docs/linter/plugins.mdx
+++ b/src/content/docs/linter/plugins.mdx
@@ -49,8 +49,6 @@ $ biome lint
 Plugins can also suggest code rewrites using the `=>` operator:
 
 ```grit
-language js
-
 `console.log($msg)` as $call where {
     register_diagnostic(
         span = $call,