From 06ccc147d49585b3c19357572995c2e02c78bb4b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Erel=20=C3=87olak?= <erelcolak@gmail.com>
Date: Wed, 16 Sep 2026 16:18:51 +0300
Subject: [PATCH] docs: add documentation for the `@ai` tag

Documents the `@ai` block tag proposed in jsdoc/jsdoc#2182, which gives notes
left by AI tools a single, predictable place inside a JSDoc comment instead of
scattered inline comments.

The page follows the layout used by the other block tag pages: syntax, an
overview, and an example. No index changes are needed, because the "Block tags"
section of the table of contents is generated from the `blockTags` collection.
---
 content/tags-ai.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 content/tags-ai.md

diff --git a/content/tags-ai.md b/content/tags-ai.md
new file mode 100644
index 0000000..1638a62
--- /dev/null
+++ b/content/tags-ai.md
@@ -0,0 +1,37 @@
+---
+tag: ai
+tags: blockTags
+description: Document notes left by AI tools.
+---
+
+## Syntax
+
+`@ai text of the note.`
+
+
+## Overview
+
+The @ai tag documents a note left by an AI tool, such as a record of a change the tool made or the
+reasoning behind a decision. Without a dedicated place for these notes, AI tools tend to leave them
+as inline comments throughout your code, which makes the surrounding code harder to read.
+
+You can use the @ai tag more than once in a single JSDoc comment, so that notes from several tools,
+or from several sessions, accumulate instead of overwriting each other.
+
+
+## Examples
+
+::: example "Using the @ai tag"
+
+```js
+/**
+ * Fetches all users from the API.
+ *
+ * @ai Refactored to use async/await.
+ * @ai Added a null guard for the user ID.
+ */
+function getUsers() {
+    // ...
+}
+```
+:::