feat(api-docs): add tag post-processor and per-product tags.yml configs

Add apply-tag-config.ts that reads colocated tags.yml files and patches
OpenAPI spec tags in place (descriptions, x-related links, renames).
Runs between getswagger.sh and generate-openapi-articles.ts in the
build pipeline.

Create tags.yml for all 11 product specs:
- Core, Enterprise: extracted from existing spec tag metadata
- v2-compat, v2, v1: new descriptions and x-related links

Include test suite (16 assertions) covering description setting, tag
rename propagation, x-related links, stale/uncovered tag warnings,
silent skip when no config, and malformed YAML failure.

api-docs/enterprise_influxdb/v1/tags.yml

@@ -0,0 +1,34 @@
+tags:
+  System Information:
+    description: >
+      Check server status, health, and version information for an InfluxDB
+      Enterprise v1 instance.
+
+  Query:
+    description: >
+      Query data using InfluxQL via the `/query` endpoint, supporting both read
+      queries (SELECT, SHOW) and management queries (CREATE, DROP, ALTER).
+
+  Write:
+    description: >
+      Write time series data to InfluxDB Enterprise v1 in line protocol format
+      using the `/write` endpoint. Use the `consistency` parameter to control
+      write consistency across cluster nodes.
+
+  Debug:
+    description: >
+      Access debugging and profiling endpoints for troubleshooting and
+      performance analysis of an InfluxDB Enterprise v1 instance.
+
+  v2 Compatibility:
+    description: >
+      InfluxDB v2-compatible API endpoints that allow InfluxDB 2.x client
+      libraries to work with InfluxDB Enterprise 1.8+, using the Token
+      authentication scheme with v1 credentials.
+
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB Enterprise v1 using basic
+      authentication, query string credentials, or the v2-compatible token
+      scheme.
+    # x-traitTag: true — informational tag, no operations

api-docs/influxdb/cloud/v2/tags.yml

@@ -0,0 +1,247 @@
+tags:
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB Cloud using API tokens with token,
+      basic, or querystring authentication schemes.
+    # x-traitTag: true — informational tag, no operations
+
+  Authorizations (API tokens):
+    description: >
+      Create and manage API token authorizations that grant read and write
+      permissions to InfluxDB Cloud organization resources.
+    x-related:
+      - title: Manage API tokens
+        href: /influxdb/cloud/security/tokens/
+
+  Bucket Schemas:
+    description: >
+      Manage explicit schemas for InfluxDB Cloud buckets to enforce column
+      names and data types for measurement data.
+
+  Buckets:
+    description: >
+      Create and manage named storage locations (buckets) in InfluxDB Cloud,
+      each with a configurable retention period.
+    x-related:
+      - title: Manage buckets
+        href: /influxdb/cloud/organizations/buckets/
+
+  Cells:
+    description: >
+      Manage cells within InfluxDB Cloud dashboards.
+
+  Checks:
+    description: >
+      Create and manage monitoring checks that query data on a schedule and
+      generate notification statuses in InfluxDB Cloud.
+
+  Common parameters:
+    description: >
+      Common query parameters used by InfluxDB Cloud API endpoints, including
+      `bucket`, `bucketID`, `org`, and `orgID`.
+    # x-traitTag: true — informational tag, no operations
+
+  Config:
+    description: >
+      Retrieve configuration information for an InfluxDB Cloud instance.
+
+  Dashboards:
+    description: >
+      Create and manage dashboards in InfluxDB Cloud.
+
+  DBRPs:
+    description: >
+      Manage database and retention policy (DBRP) mappings that route InfluxDB
+      v1-compatible requests to InfluxDB Cloud buckets.
+    x-related:
+      - title: Database and retention policy mapping
+        href: /influxdb/cloud/reference/api/influxdb-1x/dbrp/
+
+  Delete:
+    description: >
+      Delete time series data from an InfluxDB Cloud bucket by specifying a
+      time range and optional tag predicate.
+
+  Headers:
+    description: >
+      Standard HTTP request headers used by InfluxDB Cloud API endpoints,
+      including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
+    # x-traitTag: true — informational tag, no operations
+
+  Invokable Scripts:
+    description: >
+      Store, manage, and execute custom Flux scripts in InfluxDB Cloud.
+      Scripts accept runtime parameters and can be invoked via dedicated
+      endpoints.
+
+  Labels:
+    description: >
+      Create and manage labels for organizing InfluxDB Cloud resources such as
+      dashboards, tasks, and buckets.
+
+  Legacy Authorizations:
+    description: >
+      Manage legacy (v1-compatible) authorization credentials in InfluxDB Cloud.
+
+  Legacy Query:
+    description: >
+      Query data using InfluxQL via the v1-compatible `/query` endpoint in
+      InfluxDB Cloud.
+
+  Legacy Write:
+    description: >
+      Write data using the v1-compatible `/write` endpoint in InfluxDB Cloud.
+
+  Limits:
+    description: >
+      Retrieve rate limits and usage quotas for an InfluxDB Cloud organization.
+
+  NotificationEndpoints:
+    description: >
+      Create and manage notification endpoints that receive alert notifications
+      from InfluxDB Cloud monitoring checks.
+
+  NotificationRules:
+    description: >
+      Create and manage notification rules that define when and how InfluxDB
+      Cloud sends notifications to configured endpoints.
+
+  Organizations:
+    description: >
+      View and manage InfluxDB Cloud organizations, which are workspaces that
+      group users, buckets, and resources.
+    x-related:
+      - title: View and manage organizations
+        href: /influxdb/cloud/organizations/
+
+  Pagination:
+    description: >
+      Query parameters for paginating results from list operations in the
+      InfluxDB Cloud API.
+    # x-traitTag: true — informational tag, no operations
+
+  Ping:
+    description: >
+      Check the availability of the InfluxDB Cloud instance.
+
+  Query data:
+    description: >
+      Retrieve data, analyze queries, and get query suggestions using the
+      InfluxDB Cloud query API.
+    x-related:
+      - title: Query data
+        href: /influxdb/cloud/query-data/
+
+  Quick start:
+    description: >
+      Get started authenticating, writing, and querying data with the InfluxDB
+      Cloud API.
+    # x-traitTag: true — informational tag, no operations
+
+  Resources:
+    description: >
+      Retrieve a list of top-level resource types available in the InfluxDB
+      Cloud API.
+
+  Response codes:
+    description: >
+      Standard HTTP status codes returned by InfluxDB Cloud API endpoints and
+      their meanings.
+    # x-traitTag: true — informational tag, no operations
+
+  Routes:
+    description: >
+      Retrieve top-level routes for the InfluxDB Cloud API.
+
+  Rules:
+    description: >
+      Manage notification rules in InfluxDB Cloud.
+
+  Secrets:
+    description: >
+      Create and manage secrets (key-value pairs) for use in InfluxDB Cloud
+      Flux scripts and tasks.
+
+  Security and access endpoints:
+    description: >
+      Endpoints for managing authentication and access control in InfluxDB
+      Cloud.
+
+  Setup:
+    description: >
+      Configure an initial InfluxDB Cloud instance, including creating the
+      initial user, organization, and bucket.
+
+  Signin:
+    description: >
+      Create a user session by signing in with username and password
+      credentials.
+
+  Signout:
+    description: >
+      End a user session by signing out.
+
+  Supported operations:
+    description: >
+      Overview of the common CRUD operations supported by the InfluxDB Cloud
+      API.
+    # x-traitTag: true — informational tag, no operations
+
+  System information endpoints:
+    description: >
+      Endpoints for retrieving system-level information about the InfluxDB
+      Cloud instance.
+
+  Tasks:
+    description: >
+      Schedule and manage Flux tasks that process and transform data on a
+      recurring basis in InfluxDB Cloud.
+    x-related:
+      - title: Get started with tasks
+        href: /influxdb/cloud/process-data/get-started/
+
+  Telegraf Plugins:
+    description: >
+      Retrieve available Telegraf plugin configuration templates for use with
+      InfluxDB Cloud.
+
+  Telegrafs:
+    description: >
+      Create and manage Telegraf agent configurations that collect and write
+      data to InfluxDB Cloud.
+
+  Templates:
+    description: >
+      Export and apply InfluxDB templates, and manage template stacks for
+      InfluxDB Cloud.
+    x-related:
+      - title: InfluxDB templates
+        href: /influxdb/cloud/influxdb-templates/
+
+  Usage:
+    description: >
+      Retrieve usage metrics and cardinality data for an InfluxDB Cloud
+      organization.
+
+  Users:
+    description: >
+      View specific users that are members of your InfluxDB Cloud organization.
+    x-related:
+      - title: Manage users
+        href: /influxdb/cloud/organizations/users/
+
+  Variables:
+    description: >
+      Create and manage variables for use in InfluxDB Cloud dashboards.
+
+  Views:
+    description: >
+      Manage cell views within InfluxDB Cloud dashboards.
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB Cloud buckets in line protocol format
+      using the `/api/v2/write` endpoint.
+    x-related:
+      - title: Write data
+        href: /influxdb/cloud/write-data/

api-docs/influxdb/v1/tags.yml

@@ -0,0 +1,32 @@
+tags:
+  System Information:
+    description: >
+      Check server status, health, and version information for an InfluxDB
+      v1 instance.
+
+  Query:
+    description: >
+      Query data using InfluxQL via the `/query` endpoint, supporting both read
+      queries (SELECT, SHOW) and management queries (CREATE, DROP, ALTER).
+
+  Write:
+    description: >
+      Write time series data to InfluxDB v1 in line protocol format using the
+      `/write` endpoint.
+
+  Debug:
+    description: >
+      Access debugging and profiling endpoints for troubleshooting and
+      performance analysis of an InfluxDB v1 instance.
+
+  v2 Compatibility:
+    description: >
+      InfluxDB v2-compatible API endpoints that allow InfluxDB 2.x client
+      libraries to work with InfluxDB 1.8+, using the Token authentication
+      scheme with v1 credentials.
+
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB v1 using basic authentication,
+      query string credentials, or the v2-compatible token scheme.
+    # x-traitTag: true — informational tag, no operations

api-docs/influxdb/v2/v2/tags.yml

@@ -0,0 +1,285 @@
+tags:
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB OSS v2 using API tokens with
+      token, basic, or querystring authentication schemes.
+    # x-traitTag: true — informational tag, no operations
+
+  Authorizations (API tokens):
+    description: >
+      Create and manage API token authorizations that grant read and write
+      permissions to InfluxDB OSS v2 organization resources.
+    x-related:
+      - title: Manage API tokens
+        href: /influxdb/v2/security/tokens/
+
+  Authorizations (v1-compatible):
+    description: >
+      Manage v1-compatible legacy authorization credentials in InfluxDB OSS v2.
+
+  Backup:
+    description: >
+      Back up InfluxDB OSS v2 data, including time series data and metadata,
+      for use in restore operations.
+
+  Buckets:
+    description: >
+      Create and manage named storage locations (buckets) in InfluxDB OSS v2,
+      each with a configurable retention period.
+    x-related:
+      - title: Manage buckets
+        href: /influxdb/v2/organizations/buckets/
+
+  Cells:
+    description: >
+      Manage cells within InfluxDB OSS v2 dashboards.
+
+  Checks:
+    description: >
+      Create and manage monitoring checks that query data on a schedule and
+      generate notification statuses in InfluxDB OSS v2.
+
+  Common parameters:
+    description: >
+      Common query parameters used by InfluxDB OSS v2 API endpoints, including
+      `bucket`, `bucketID`, `org`, and `orgID`.
+    # x-traitTag: true — informational tag, no operations
+
+  Compatibility endpoints:
+    description: >
+      InfluxDB v1-compatible API endpoints for backward compatibility with
+      InfluxDB 1.x clients, tools, and integrations such as Grafana and
+      Telegraf.
+
+  Config:
+    description: >
+      Retrieve configuration information for an InfluxDB OSS v2 instance.
+
+  Dashboards:
+    description: >
+      Create and manage dashboards in InfluxDB OSS v2.
+
+  DBRPs:
+    description: >
+      Manage database and retention policy (DBRP) mappings that route InfluxDB
+      v1-compatible requests to InfluxDB OSS v2 buckets.
+    x-related:
+      - title: Database and retention policy mapping
+        href: /influxdb/v2/reference/api/influxdb-1x/dbrp/
+
+  Debug:
+    description: >
+      Generate Go runtime profiling and trace reports for troubleshooting and
+      performance analysis of an InfluxDB OSS v2 instance.
+
+  Delete:
+    description: >
+      Delete time series data from an InfluxDB OSS v2 bucket by specifying a
+      time range and optional tag predicate.
+
+  Headers:
+    description: >
+      Standard HTTP request headers used by InfluxDB OSS v2 API endpoints,
+      including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
+    # x-traitTag: true — informational tag, no operations
+
+  Health:
+    description: >
+      Check the health and readiness of an InfluxDB OSS v2 instance.
+
+  Labels:
+    description: >
+      Create and manage labels for organizing InfluxDB OSS v2 resources such as
+      dashboards, tasks, and buckets.
+
+  Metrics:
+    description: >
+      Retrieve internal metrics for an InfluxDB OSS v2 instance in Prometheus
+      exposition format.
+
+  NotificationEndpoints:
+    description: >
+      Create and manage notification endpoints that receive alert notifications
+      from InfluxDB OSS v2 monitoring checks.
+
+  NotificationRules:
+    description: >
+      Create and manage notification rules that define when and how InfluxDB
+      OSS v2 sends notifications to configured endpoints.
+
+  Organizations:
+    description: >
+      Create and manage InfluxDB OSS v2 organizations, which are workspaces
+      that group users, buckets, and resources.
+    x-related:
+      - title: Manage organizations
+        href: /influxdb/v2/organizations/
+
+  Pagination:
+    description: >
+      Query parameters for paginating results from list operations in the
+      InfluxDB OSS v2 API.
+    # x-traitTag: true — informational tag, no operations
+
+  Ping:
+    description: >
+      Check the availability of an InfluxDB OSS v2 instance.
+
+  Query data:
+    description: >
+      Retrieve data, analyze queries, and get query suggestions using the
+      InfluxDB OSS v2 query API.
+    x-related:
+      - title: Query data
+        href: /influxdb/v2/query-data/
+
+  Query data (v1-compatible):
+    description: >
+      Query data in InfluxDB OSS v2 using InfluxQL via the v1-compatible
+      `/query` endpoint.
+
+  Quick start:
+    description: >
+      Get started authenticating, writing, and querying data with the InfluxDB
+      OSS v2 API.
+    # x-traitTag: true — informational tag, no operations
+
+  Ready:
+    description: >
+      Check whether an InfluxDB OSS v2 instance is ready to accept requests.
+
+  RemoteConnections:
+    description: >
+      Create and manage remote InfluxDB connections for replicating data from
+      an InfluxDB OSS v2 instance to a remote InfluxDB instance.
+
+  Replications:
+    description: >
+      Create and manage replication streams that copy data from an InfluxDB
+      OSS v2 bucket to a remote InfluxDB instance.
+
+  Resources:
+    description: >
+      Retrieve a list of top-level resource types available in the InfluxDB
+      OSS v2 API.
+
+  Response codes:
+    description: >
+      Standard HTTP status codes returned by InfluxDB OSS v2 API endpoints and
+      their meanings.
+    # x-traitTag: true — informational tag, no operations
+
+  Restore:
+    description: >
+      Restore InfluxDB OSS v2 data from a backup, including time series data
+      and metadata.
+
+  Routes:
+    description: >
+      Retrieve top-level routes for the InfluxDB OSS v2 API.
+
+  Rules:
+    description: >
+      Manage notification rules in InfluxDB OSS v2.
+
+  Scraper Targets:
+    description: >
+      Create and manage Prometheus scraper targets that collect metrics and
+      write them to InfluxDB OSS v2 buckets.
+
+  Secrets:
+    description: >
+      Create and manage secrets (key-value pairs) for use in InfluxDB OSS v2
+      Flux scripts and tasks.
+
+  Security and access endpoints:
+    description: >
+      Endpoints for managing authentication and access control in InfluxDB
+      OSS v2.
+
+  Setup:
+    description: >
+      Configure a new InfluxDB OSS v2 instance, including creating the initial
+      user, organization, bucket, and API token.
+    x-related:
+      - title: Set up InfluxDB
+        href: /influxdb/v2/get-started/
+
+  Signin:
+    description: >
+      Create a user session by signing in with username and password
+      credentials.
+
+  Signout:
+    description: >
+      End a user session by signing out.
+
+  Sources:
+    description: >
+      Manage data sources configured in InfluxDB OSS v2.
+
+  Supported operations:
+    description: >
+      Overview of the common CRUD operations supported by the InfluxDB OSS v2
+      API.
+    # x-traitTag: true — informational tag, no operations
+
+  System information endpoints:
+    description: >
+      Endpoints for retrieving system-level information about the InfluxDB
+      OSS v2 instance.
+
+  Tasks:
+    description: >
+      Schedule and manage Flux tasks that process and transform data on a
+      recurring basis in InfluxDB OSS v2.
+    x-related:
+      - title: Get started with tasks
+        href: /influxdb/v2/process-data/get-started/
+
+  Telegraf Plugins:
+    description: >
+      Retrieve available Telegraf plugin configuration templates for use with
+      InfluxDB OSS v2.
+
+  Telegrafs:
+    description: >
+      Create and manage Telegraf agent configurations that collect and write
+      data to InfluxDB OSS v2.
+
+  Templates:
+    description: >
+      Export and apply InfluxDB templates, and manage template stacks for
+      InfluxDB OSS v2.
+    x-related:
+      - title: InfluxDB templates
+        href: /influxdb/v2/influxdb-templates/
+
+  Users:
+    description: >
+      Create and manage users that have access to InfluxDB OSS v2 organizations
+      and resources.
+    x-related:
+      - title: Manage users
+        href: /influxdb/v2/users/
+
+  Variables:
+    description: >
+      Create and manage variables for use in InfluxDB OSS v2 dashboards.
+
+  Views:
+    description: >
+      Manage cell views within InfluxDB OSS v2 dashboards.
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB OSS v2 buckets in line protocol format
+      using the `/api/v2/write` endpoint.
+    x-related:
+      - title: Write data
+        href: /influxdb/v2/write-data/
+
+  Write data (v1-compatible):
+    description: >
+      Write data to InfluxDB OSS v2 using the v1-compatible `/write` endpoint
+      with line protocol.

api-docs/influxdb3/cloud-dedicated/management/tags.yml

@@ -0,0 +1,30 @@
+tags:
+  Database tokens:
+    description: >
+      Create and manage database tokens that authorize read and write access to
+      InfluxDB 3 Cloud Dedicated databases.
+    x-related:
+      - title: Manage database tokens
+        href: /influxdb3/cloud-dedicated/admin/tokens/
+
+  Databases:
+    description: >
+      Create and manage databases in an InfluxDB 3 Cloud Dedicated cluster,
+      including setting retention periods and custom partition templates.
+    x-related:
+      - title: Manage databases
+        href: /influxdb3/cloud-dedicated/admin/databases/
+
+  Quick start:
+    description: >
+      Get started creating a database, issuing tokens, and writing data with
+      the InfluxDB 3 Cloud Dedicated Management API.
+    # x-traitTag: true — informational tag, no operations
+
+  Tables:
+    description: >
+      Manage tables in an InfluxDB 3 Cloud Dedicated database, including
+      creating tables with custom column schemas.
+    x-related:
+      - title: Manage tables
+        href: /influxdb3/cloud-dedicated/admin/tables/

api-docs/influxdb3/cloud-dedicated/tags.yml

@@ -0,0 +1,70 @@
+tags:
+  API compatibility:
+    description: >
+      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
+      available in InfluxDB 3 Cloud Dedicated.
+    # x-traitTag: true — informational tag, no operations
+
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB 3 Cloud Dedicated using database
+      tokens with bearer, token, basic, or querystring authentication schemes.
+    # x-traitTag: true — informational tag, no operations
+
+  Common parameters:
+    description: >
+      Common query parameters used by InfluxDB 3 Cloud Dedicated API endpoints,
+      including the required `database` or `db` parameter.
+    # x-traitTag: true — informational tag, no operations
+
+  Headers:
+    description: >
+      Standard HTTP request headers used by InfluxDB 3 Cloud Dedicated API
+      endpoints, including `Accept`, `Authorization`, `Content-Length`, and
+      `Content-Type`.
+    # x-traitTag: true — informational tag, no operations
+
+  Ping:
+    description: >
+      Check the availability of the InfluxDB 3 Cloud Dedicated instance.
+
+  Query data:
+    description: >
+      Query data stored in InfluxDB 3 Cloud Dedicated using InfluxQL via the
+      v1-compatible `/query` endpoint. Use Flight+gRPC for SQL or InfluxQL
+      queries with Arrow format output.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/cloud-dedicated/get-started/query/
+      - title: Execute queries
+        href: /influxdb3/cloud-dedicated/query-data/execute-queries/
+
+  Quick start:
+    description: >
+      Get started authenticating, creating a database, and writing and querying
+      data with the InfluxDB 3 Cloud Dedicated API.
+    # x-traitTag: true — informational tag, no operations
+
+  Response codes:
+    description: >
+      Standard HTTP status codes returned by InfluxDB 3 Cloud Dedicated API
+      endpoints and their meanings.
+    # x-traitTag: true — informational tag, no operations
+
+  System information endpoints:
+    description: >
+      Endpoints for retrieving system-level information about the InfluxDB 3
+      Cloud Dedicated instance.
+
+  Usage:
+    description: >
+      Retrieve usage metrics for an InfluxDB 3 Cloud Dedicated instance.
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB 3 Cloud Dedicated databases using the
+      v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write`
+      endpoint with line protocol.
+    x-related:
+      - title: Write data
+        href: /influxdb3/cloud-dedicated/write-data/

api-docs/influxdb3/cloud-serverless/tags.yml

@@ -0,0 +1,248 @@
+tags:
+  API compatibility:
+    description: >
+      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
+      available in InfluxDB 3 Cloud Serverless.
+    # x-traitTag: true — informational tag, no operations
+
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB 3 Cloud Serverless using API tokens
+      with token, basic, or querystring authentication schemes.
+    # x-traitTag: true — informational tag, no operations
+
+  Authorizations (API tokens):
+    description: >
+      Create and manage API token authorizations that grant read and write
+      permissions to InfluxDB 3 Cloud Serverless organization resources.
+    x-related:
+      - title: Manage API tokens
+        href: /influxdb3/cloud-serverless/security/tokens/
+
+  Bucket Schemas:
+    description: >
+      Manage explicit schemas for InfluxDB 3 Cloud Serverless buckets to
+      enforce column names and data types.
+
+  Buckets:
+    description: >
+      Create and manage named storage locations (buckets) in InfluxDB 3 Cloud
+      Serverless, each with a configurable retention period.
+    x-related:
+      - title: Manage buckets
+        href: /influxdb3/cloud-serverless/admin/buckets/
+
+  Cells:
+    description: >
+      Manage cells within InfluxDB 3 Cloud Serverless dashboards.
+
+  Checks:
+    description: >
+      Create and manage monitoring checks that query data and generate
+      notification statuses in InfluxDB 3 Cloud Serverless.
+
+  Common parameters:
+    description: >
+      Common query parameters used by InfluxDB 3 Cloud Serverless API
+      endpoints, including `bucket`, `bucketID`, `org`, and `orgID`.
+    # x-traitTag: true — informational tag, no operations
+
+  Config:
+    description: >
+      Retrieve configuration information for an InfluxDB 3 Cloud Serverless
+      instance.
+
+  Dashboards:
+    description: >
+      Create and manage dashboards in InfluxDB 3 Cloud Serverless.
+
+  DBRPs:
+    description: >
+      Manage database and retention policy (DBRP) mappings that route InfluxDB
+      v1-compatible requests to InfluxDB 3 Cloud Serverless buckets.
+    x-related:
+      - title: Database and retention policy mapping
+        href: /influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/
+
+  Delete:
+    description: >
+      Delete time series data from an InfluxDB 3 Cloud Serverless bucket by
+      specifying a time range and optional predicate.
+
+  Headers:
+    description: >
+      Standard HTTP request headers used by InfluxDB 3 Cloud Serverless API
+      endpoints, including `Accept`, `Authorization`, `Content-Length`, and
+      `Content-Type`.
+    # x-traitTag: true — informational tag, no operations
+
+  Invokable Scripts:
+    description: >
+      Store, manage, and execute custom Flux scripts in InfluxDB 3 Cloud
+      Serverless. Scripts accept runtime parameters and can be invoked via
+      dedicated endpoints.
+
+  Labels:
+    description: >
+      Create and manage labels for organizing InfluxDB 3 Cloud Serverless
+      resources.
+
+  Legacy Authorizations:
+    description: >
+      Manage legacy (v1-compatible) authorization credentials in InfluxDB 3
+      Cloud Serverless.
+
+  Limits:
+    description: >
+      Retrieve rate limits and usage quotas for an InfluxDB 3 Cloud Serverless
+      organization.
+
+  NotificationEndpoints:
+    description: >
+      Create and manage notification endpoints that receive alert notifications
+      from InfluxDB 3 Cloud Serverless monitoring checks.
+
+  NotificationRules:
+    description: >
+      Create and manage notification rules that define when and how
+      InfluxDB 3 Cloud Serverless sends notifications to endpoints.
+
+  Organizations:
+    description: >
+      View and manage InfluxDB 3 Cloud Serverless organizations, which are
+      workspaces that group users, buckets, and resources.
+    x-related:
+      - title: View and manage organizations
+        href: /influxdb3/cloud-serverless/admin/
+
+  Pagination:
+    description: >
+      Query parameters for paginating results from list operations in the
+      InfluxDB 3 Cloud Serverless API.
+    # x-traitTag: true — informational tag, no operations
+
+  Ping:
+    description: >
+      Check the availability of the InfluxDB 3 Cloud Serverless instance.
+
+  Query data:
+    description: >
+      Query data stored in InfluxDB 3 Cloud Serverless using InfluxQL via the
+      v1-compatible `/query` endpoint, or using SQL and InfluxQL via
+      Flight+gRPC clients.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/cloud-serverless/get-started/query/
+      - title: Execute queries
+        href: /influxdb3/cloud-serverless/query-data/execute-queries/
+
+  Quick start:
+    description: >
+      Get started writing and querying data with the InfluxDB 3 Cloud
+      Serverless API.
+    # x-traitTag: true — informational tag, no operations
+
+  Resources:
+    description: >
+      Retrieve a list of top-level resource types available in the InfluxDB 3
+      Cloud Serverless API.
+
+  Response codes:
+    description: >
+      Standard HTTP status codes returned by InfluxDB 3 Cloud Serverless API
+      endpoints and their meanings.
+    # x-traitTag: true — informational tag, no operations
+
+  Routes:
+    description: >
+      Retrieve top-level routes for the InfluxDB 3 Cloud Serverless API.
+
+  Rules:
+    description: >
+      Manage notification rules in InfluxDB 3 Cloud Serverless.
+
+  Secrets:
+    description: >
+      Create and manage secrets (key-value pairs) for use in InfluxDB 3 Cloud
+      Serverless Flux scripts and tasks.
+
+  Security and access endpoints:
+    description: >
+      Endpoints for managing authentication and access control in InfluxDB 3
+      Cloud Serverless.
+
+  Setup:
+    description: >
+      Configure an initial InfluxDB 3 Cloud Serverless instance, including
+      creating the initial user, organization, and bucket.
+
+  Signin:
+    description: >
+      Create a user session by signing in with username and password
+      credentials.
+
+  Signout:
+    description: >
+      End a user session by signing out.
+
+  Supported operations:
+    description: >
+      Overview of the common CRUD operations supported by the InfluxDB 3 Cloud
+      Serverless API.
+    # x-traitTag: true — informational tag, no operations
+
+  System information endpoints:
+    description: >
+      Endpoints for retrieving system-level information about the InfluxDB 3
+      Cloud Serverless instance.
+
+  Tasks:
+    description: >
+      Schedule and manage Flux tasks that process and transform data on a
+      recurring basis in InfluxDB 3 Cloud Serverless.
+
+  Telegraf Plugins:
+    description: >
+      Retrieve available Telegraf plugin configuration templates for use with
+      InfluxDB 3 Cloud Serverless.
+
+  Telegrafs:
+    description: >
+      Create and manage Telegraf agent configurations that collect and write
+      data to InfluxDB 3 Cloud Serverless.
+
+  Templates:
+    description: >
+      Export and apply InfluxDB templates, and manage template stacks for
+      InfluxDB 3 Cloud Serverless.
+
+  Usage:
+    description: >
+      Retrieve usage metrics and cardinality data for an InfluxDB 3 Cloud
+      Serverless organization.
+
+  Users:
+    description: >
+      View specific users that are members of your InfluxDB 3 Cloud Serverless
+      organization.
+    x-related:
+      - title: Manage users
+        href: /influxdb3/cloud-serverless/organizations/users/
+
+  Variables:
+    description: >
+      Create and manage variables for use in InfluxDB 3 Cloud Serverless
+      dashboards.
+
+  Views:
+    description: >
+      Manage cell views within InfluxDB 3 Cloud Serverless dashboards.
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB 3 Cloud Serverless buckets using the
+      v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write`
+      endpoint with line protocol.
+    x-related:
+      - title: Write data
+        href: /influxdb3/cloud-serverless/write-data/

api-docs/influxdb3/clustered/management/tags.yml

@@ -0,0 +1,30 @@
+tags:
+  Database tokens:
+    description: >
+      Create and manage database tokens that authorize read and write access to
+      InfluxDB 3 Clustered databases.
+    x-related:
+      - title: Manage database tokens
+        href: /influxdb3/clustered/admin/tokens/
+
+  Databases:
+    description: >
+      Create and manage databases in an InfluxDB 3 Clustered cluster, including
+      setting retention periods and custom partition templates.
+    x-related:
+      - title: Manage databases
+        href: /influxdb3/clustered/admin/databases/
+
+  Quick start:
+    description: >
+      Get started creating a database, issuing tokens, and writing data with
+      the InfluxDB 3 Clustered Management API.
+    # x-traitTag: true — informational tag, no operations
+
+  Tables:
+    description: >
+      Manage tables in an InfluxDB 3 Clustered database, including creating
+      tables with custom column schemas.
+    x-related:
+      - title: Manage tables
+        href: /influxdb3/clustered/admin/tables/

api-docs/influxdb3/clustered/tags.yml

@@ -0,0 +1,69 @@
+tags:
+  API compatibility:
+    description: >
+      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
+      available in InfluxDB 3 Clustered.
+    # x-traitTag: true — informational tag, no operations
+
+  Authentication:
+    description: >
+      Authenticate API requests to InfluxDB 3 Clustered using database tokens
+      with bearer, token, basic, or querystring authentication schemes.
+    # x-traitTag: true — informational tag, no operations
+
+  Common parameters:
+    description: >
+      Common query parameters used by InfluxDB 3 Clustered API endpoints,
+      including the required `database` or `db` parameter.
+    # x-traitTag: true — informational tag, no operations
+
+  Headers:
+    description: >
+      Standard HTTP request headers used by InfluxDB 3 Clustered API endpoints,
+      including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
+    # x-traitTag: true — informational tag, no operations
+
+  Ping:
+    description: >
+      Check the availability of an InfluxDB 3 Clustered instance.
+
+  Query data:
+    description: >
+      Query data stored in InfluxDB 3 Clustered using InfluxQL via the
+      v1-compatible `/query` endpoint. Use Flight+gRPC for SQL or InfluxQL
+      queries with Arrow format output.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/clustered/get-started/query/
+      - title: Execute queries
+        href: /influxdb3/clustered/query-data/execute-queries/
+
+  Quick start:
+    description: >
+      Get started authenticating, creating a database, and writing and querying
+      data with the InfluxDB 3 Clustered API.
+    # x-traitTag: true — informational tag, no operations
+
+  Response codes:
+    description: >
+      Standard HTTP status codes returned by InfluxDB 3 Clustered API endpoints
+      and their meanings.
+    # x-traitTag: true — informational tag, no operations
+
+  System information endpoints:
+    description: >
+      Endpoints for retrieving system-level information about the InfluxDB 3
+      Clustered instance.
+
+  Usage:
+    description: >
+      Retrieve usage metrics for an InfluxDB 3 Clustered instance.
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB 3 Clustered databases using the
+      v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write`
+      endpoint with line protocol.
+    x-related:
+      - title: Write data
+        href: /influxdb3/clustered/write-data/

api-docs/influxdb3/core/v3/tags.yml

@@ -0,0 +1,96 @@
+tags:
+  Authentication:
+    description: >
+      Authenticate API requests using bearer tokens, token scheme, basic
+      authentication, or querystring credentials.
+      See the Security Schemes section for details on each method.
+    # x-traitTag: true — informational tag, no operations
+
+  Cache distinct values:
+    description: >
+      Manage the Distinct Value Cache (DVC), an in-memory cache that stores
+      distinct values for specific columns in a table to improve query
+      performance for distinct tag and field value lookups.
+    x-related:
+      - title: Manage the Distinct Value Cache
+        href: /influxdb3/core/admin/distinct-value-cache/
+
+  Cache last value:
+    description: >
+      Manage the Last Value Cache (LVC), an in-memory cache that stores the
+      most recent N values for specific fields in a table to improve query
+      performance for last-value lookups.
+    x-related:
+      - title: Manage the Last Value Cache
+        href: /influxdb3/core/admin/last-value-cache/
+
+  Migrate from InfluxDB v1 or v2:
+    description: >
+      Reference information for migrating existing InfluxDB v1 or v2 workloads
+      to InfluxDB 3 Core using compatibility endpoints.
+    # x-traitTag: true — informational tag, no operations
+
+  Database:
+    description: >
+      Create, list, and delete databases in InfluxDB 3 Core.
+    x-related:
+      - title: Manage databases
+        href: /influxdb3/core/admin/databases/
+
+  Headers and parameters:
+    description: >
+      Common HTTP request headers and query parameters used by InfluxDB 3 Core
+      API endpoints.
+    # x-traitTag: true — informational tag, no operations
+
+  Processing engine:
+    description: >
+      Manage Processing engine triggers, test plugins, and invoke On Request
+      plugins. The processing engine is an embedded Python VM that runs plugins
+      in response to database events.
+    x-related:
+      - title: Processing engine and Python plugins
+        href: /influxdb3/core/processing-engine/
+
+  Query data:
+    description: >
+      Query data stored in InfluxDB 3 Core using SQL or InfluxQL.
+    x-related:
+      - title: Query data
+        href: /influxdb3/core/query-data/
+
+  Quick start:
+    description: >
+      Get started authenticating, writing, and querying data with the
+      InfluxDB 3 Core API.
+    # x-traitTag: true — informational tag, no operations
+
+  Server information:
+    description: >
+      Retrieve server metrics, health status, and version information for
+      InfluxDB 3 Core.
+
+  Table:
+    description: >
+      Manage table schemas in an InfluxDB 3 Core database.
+    x-related:
+      - title: Manage tables
+        href: /influxdb3/core/admin/tables/
+
+  Auth token:
+    description: >
+      Create and manage tokens used for authenticating and authorizing access
+      to InfluxDB 3 Core resources.
+    x-related:
+      - title: Manage tokens
+        href: /influxdb3/core/admin/tokens/
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB 3 Core in line protocol format using
+      the v1, v2, or v3 write endpoints.
+    x-related:
+      - title: Write data using HTTP APIs
+        href: /influxdb3/core/write-data/http-api/
+      - title: Line protocol reference
+        href: /influxdb3/core/reference/syntax/line-protocol/

api-docs/influxdb3/enterprise/v3/tags.yml

@@ -0,0 +1,83 @@
+tags:
+  Authentication:
+    description: >
+      Authenticate API requests using bearer tokens, token scheme, basic
+      authentication, or querystring credentials.
+      See the Security Schemes section for details on each method.
+    # x-traitTag: true — informational tag, no operations
+
+  Cache data:
+    description: >
+      Manage in-memory caches for InfluxDB 3 Enterprise, including the Distinct
+      Value Cache (DVC) for distinct column values and the Last Value Cache
+      (LVC) for most-recent field values.
+    x-related:
+      - title: Manage the Distinct Value Cache
+        href: /influxdb3/enterprise/admin/distinct-value-cache/
+      - title: Manage the Last Value Cache
+        href: /influxdb3/enterprise/admin/last-value-cache/
+
+  Database:
+    description: >
+      Create, list, and delete databases in InfluxDB 3 Enterprise.
+    x-related:
+      - title: Manage databases
+        href: /influxdb3/enterprise/admin/databases/
+
+  Headers and parameters:
+    description: >
+      Common HTTP request headers and query parameters used by InfluxDB 3
+      Enterprise API endpoints.
+    # x-traitTag: true — informational tag, no operations
+
+  Processing engine:
+    description: >
+      Manage Processing engine triggers, test plugins, and invoke On Request
+      plugins. The processing engine is an embedded Python VM that runs plugins
+      in response to database events.
+    x-related:
+      - title: Processing engine and Python plugins
+        href: /influxdb3/enterprise/processing-engine/
+
+  Query data:
+    description: >
+      Query data stored in InfluxDB 3 Enterprise using SQL or InfluxQL.
+    x-related:
+      - title: Query data
+        href: /influxdb3/enterprise/query-data/
+
+  Quick start:
+    description: >
+      Get started authenticating, writing, and querying data with the
+      InfluxDB 3 Enterprise API.
+    # x-traitTag: true — informational tag, no operations
+
+  Server information:
+    description: >
+      Retrieve server metrics, health status, and version information for
+      InfluxDB 3 Enterprise.
+
+  Table:
+    description: >
+      Manage table schemas in an InfluxDB 3 Enterprise database.
+    x-related:
+      - title: Manage tables
+        href: /influxdb3/enterprise/admin/tables/
+
+  Token:
+    description: >
+      Create and manage tokens used for authenticating and authorizing access
+      to InfluxDB 3 Enterprise resources.
+    x-related:
+      - title: Manage tokens
+        href: /influxdb3/enterprise/admin/tokens/
+
+  Write data:
+    description: >
+      Write time series data to InfluxDB 3 Enterprise in line protocol format
+      using the v1, v2, or v3 write endpoints.
+    x-related:
+      - title: Write data using HTTP APIs
+        href: /influxdb3/enterprise/write-data/http-api/
+      - title: Line protocol reference
+        href: /influxdb3/enterprise/reference/syntax/line-protocol/

api-docs/scripts/apply-tag-config.ts

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * Apply Tag Config Script
+ *
+ * Reads colocated `tags.yml` config files and patches OpenAPI spec files in
+ * place. Runs after `getswagger.sh` bundles specs and before
+ * `generate-openapi-articles.ts` generates Hugo pages.
+ *
+ * Usage:
+ *   node api-docs/scripts/dist/apply-tag-config.js           # All products
+ *   node api-docs/scripts/dist/apply-tag-config.js influxdb3/core  # One product
+ *
+ * tags.yml format (colocated with the spec file):
+ *   tags:
+ *     Write data:
+ *       description: Write line protocol data to InfluxDB.
+ *       x-related:
+ *         - title: Write data guide
+ *           href: /influxdb3/core/write-data/
+ *     Cache data:
+ *       rename: Cache distinct values
+ *       description: Query cached distinct values.
+ *
+ * @module apply-tag-config
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface RelatedLink {
+  title: string;
+  href: string;
+}
+
+interface TagConfig {
+  rename?: string;
+  description?: string;
+  'x-related'?: RelatedLink[];
+}
+
+interface TagsYml {
+  tags: Record<string, TagConfig>;
+}
+
+interface ProductConfigApi {
+  root: string;
+  [key: string]: unknown;
+}
+
+interface ProductConfigYml {
+  apis?: Record<string, ProductConfigApi>;
+  [key: string]: unknown;
+}
+
+/** An OpenAPI tag object. */
+interface OpenApiTag {
+  name: string;
+  description?: string;
+  'x-related'?: RelatedLink[];
+  [key: string]: unknown;
+}
+
+/** Minimal shape of an OpenAPI spec needed for tag patching. */
+interface OpenApiSpec {
+  tags?: OpenApiTag[];
+  paths?: Record<string, Record<string, { tags?: string[]; [k: string]: unknown }>>;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Product directories that contain a .config.yml with `apis:` entries. */
+const PRODUCT_DIRS = [
+  'influxdb3/core',
+  'influxdb3/enterprise',
+  'influxdb3/cloud-dedicated',
+  'influxdb3/cloud-serverless',
+  'influxdb3/clustered',
+  'influxdb/cloud',
+  'influxdb/v2',
+  'influxdb/v1',
+  'enterprise_influxdb/v1',
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a YAML file and return the parsed object, or null if the file does
+ * not exist.
+ *
+ * @param filePath - Absolute path to a YAML file.
+ * @returns Parsed object or null.
+ * @throws If the file exists but contains invalid YAML.
+ */
+function loadYaml<T>(filePath: string): T | null {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return yaml.load(raw) as T;
+}
+
+/**
+ * Write an object to a YAML file, preserving no special ordering.
+ *
+ * @param filePath - Absolute path to write.
+ * @param data - Object to serialise.
+ */
+function writeYaml(filePath: string, data: unknown): void {
+  fs.writeFileSync(filePath, yaml.dump(data, { lineWidth: -1 }), 'utf8');
+}
+
+/**
+ * Collect every tag name referenced across all operations in the spec.
+ *
+ * @param spec - Parsed OpenAPI spec.
+ * @returns Set of tag name strings.
+ */
+function collectOperationTags(spec: OpenApiSpec): Set<string> {
+  const found = new Set<string>();
+  for (const pathItem of Object.values(spec.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation && typeof operation === 'object' && Array.isArray(operation.tags)) {
+        for (const t of operation.tags) found.add(t as string);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Rename a tag throughout the spec: in `tags[]` and in every operation.
+ *
+ * @param spec - Parsed OpenAPI spec (mutated in place).
+ * @param oldName - Current tag name.
+ * @param newName - Replacement tag name.
+ */
+function renameTag(spec: OpenApiSpec, oldName: string, newName: string): void {
+  for (const tag of spec.tags ?? []) {
+    if (tag.name === oldName) tag.name = newName;
+  }
+  for (const pathItem of Object.values(spec.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation && typeof operation === 'object' && Array.isArray(operation.tags)) {
+        operation.tags = operation.tags.map((t: string) => (t === oldName ? newName : t));
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply one `tags.yml` config to the matching OpenAPI spec file.
+ *
+ * @param specPath - Absolute path to the OpenAPI spec (YAML).
+ * @param tagConfigPath - Absolute path to `tags.yml`.
+ * @param productLabel - Human-readable label for log messages.
+ */
+function applyTagConfig(specPath: string, tagConfigPath: string, productLabel: string): void {
+  const tagsCfg = loadYaml<TagsYml>(tagConfigPath);
+  if (!tagsCfg || !tagsCfg.tags) {
+    process.stderr.write(`[apply-tag-config] ${productLabel}: tags.yml has no 'tags' key — skipping\n`);
+    return;
+  }
+
+  const spec = loadYaml<OpenApiSpec>(specPath);
+  if (!spec) {
+    process.stderr.write(`[apply-tag-config] ${productLabel}: spec not found at ${specPath} — skipping\n`);
+    return;
+  }
+
+  if (!Array.isArray(spec.tags)) spec.tags = [];
+
+  const operationTags = collectOperationTags(spec);
+  const configKeys = Object.keys(tagsCfg.tags);
+
+  // Warn: config references a tag not in the spec
+  for (const cfgKey of configKeys) {
+    const effectiveName = tagsCfg.tags[cfgKey]?.rename ?? cfgKey;
+    if (!operationTags.has(cfgKey) && !operationTags.has(effectiveName)) {
+      process.stderr.write(
+        `[apply-tag-config] WARN ${productLabel}: config tag '${cfgKey}' not found in spec operations\n`
+      );
+    }
+  }
+
+  // Warn: spec has operation tags with no config entry
+  Array.from(operationTags).forEach((opTag) => {
+    const hasEntry = configKeys.some(
+      (k) => k === opTag || tagsCfg.tags[k]?.rename === opTag
+    );
+    if (!hasEntry) {
+      process.stderr.write(
+        `[apply-tag-config] WARN ${productLabel}: spec tag '${opTag}' has no config entry in tags.yml\n`
+      );
+    }
+  });
+
+  // Apply transformations
+  for (const [tagKey, cfg] of Object.entries(tagsCfg.tags)) {
+    const resolvedName = cfg.rename ?? tagKey;
+
+    // Rename before patching so we update the correct tag object
+    if (cfg.rename) {
+      process.stderr.write(
+        `[apply-tag-config] ${productLabel}: renaming tag '${tagKey}' → '${cfg.rename}'\n`
+      );
+      renameTag(spec, tagKey, cfg.rename);
+    }
+
+    // Find or create the tag object in spec.tags[]
+    let tagObj = spec.tags!.find((t) => t.name === resolvedName);
+    if (!tagObj) {
+      tagObj = { name: resolvedName };
+      spec.tags!.push(tagObj);
+    }
+
+    if (cfg.description !== undefined) tagObj.description = cfg.description.trim();
+    if (cfg['x-related'] !== undefined) tagObj['x-related'] = cfg['x-related'];
+  }
+
+  writeYaml(specPath, spec);
+  process.stderr.write(
+    `[apply-tag-config] ${productLabel}: patched ${configKeys.length} tag(s) in ${path.basename(specPath)}\n`
+  );
+}
+
+/**
+ * Process a single product directory: read `.config.yml`, find spec files,
+ * look for a colocated `tags.yml`, and apply transformations.
+ *
+ * @param apiDocsRoot - Absolute path to the `api-docs/` directory.
+ * @param productDir - Product directory relative to `api-docs/` (e.g. `influxdb3/core`).
+ */
+function processProduct(apiDocsRoot: string, productDir: string): void {
+  const productAbsDir = path.join(apiDocsRoot, productDir);
+  const configPath = path.join(productAbsDir, '.config.yml');
+
+  const config = loadYaml<ProductConfigYml>(configPath);
+  if (!config || !config.apis) {
+    process.stderr.write(
+      `[apply-tag-config] ${productDir}: no .config.yml or no 'apis' key — skipping\n`
+    );
+    return;
+  }
+
+  for (const [apiKey, apiEntry] of Object.entries(config.apis)) {
+    const specRelPath = apiEntry.root;
+    const specDir = path.join(productAbsDir, path.dirname(specRelPath));
+    const specAbsPath = path.join(productAbsDir, specRelPath);
+    const tagConfigPath = path.join(specDir, 'tags.yml');
+
+    if (!fs.existsSync(tagConfigPath)) continue; // silent skip — not yet configured
+
+    const label = `${productDir}/${apiKey}`;
+    applyTagConfig(specAbsPath, tagConfigPath, label);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  const args = process.argv.slice(2);
+
+  // Optional --root <path> flag for testing — overrides the default resolution.
+  let apiDocsRoot = path.resolve(__dirname, '../..'); // api-docs/scripts/dist -> api-docs/
+  let targetProduct: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--root' && args[i + 1]) {
+      apiDocsRoot = path.resolve(args[i + 1]!);
+      i++;
+    } else {
+      targetProduct = args[i];
+    }
+  }
+
+  const products = targetProduct ? [targetProduct] : PRODUCT_DIRS;
+
+  let hasError = false;
+  for (const productDir of products) {
+    try {
+      processProduct(apiDocsRoot, productDir);
+    } catch (err) {
+      process.stderr.write(
+        `[apply-tag-config] ERROR ${productDir}: ${(err as Error).message}\n`
+      );
+      hasError = true;
+    }
+  }
+
+  process.exit(hasError ? 1 : 0);
+}
+
+main();

api-docs/scripts/test-apply-tag-config.ts

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/**
+ * Tests for apply-tag-config.ts
+ *
+ * Standalone test script — no test runner required.
+ *
+ * Usage:
+ *   node api-docs/scripts/dist/test-apply-tag-config.js
+ *
+ * Creates temporary fixtures in $TMPDIR, runs the compiled script against
+ * them via child_process, and reports pass/fail for each case.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync, spawnSync } from 'child_process';
+import * as yaml from 'js-yaml';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const SCRIPT = path.resolve(__dirname, 'apply-tag-config.js');
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+interface OpenApiTag {
+  name: string;
+  description?: string;
+  'x-related'?: Array<{ title: string; href: string }>;
+  [key: string]: unknown;
+}
+
+interface OpenApiSpec {
+  openapi: string;
+  info: { title: string; version: string };
+  tags?: OpenApiTag[];
+  paths?: Record<string, Record<string, { tags?: string[]; [k: string]: unknown }>>;
+  [key: string]: unknown;
+}
+
+/**
+ * Build a minimal OpenAPI spec object.
+ *
+ * @param tags - Top-level tag definitions.
+ * @param operationTags - Tag names to attach to a synthetic GET /test operation.
+ */
+function makeSpec(tags: OpenApiTag[], operationTags: string[]): OpenApiSpec {
+  return {
+    openapi: '3.0.0',
+    info: { title: 'Test', version: '1.0.0' },
+    tags,
+    paths: {
+      '/test': {
+        get: {
+          operationId: 'testOp',
+          tags: operationTags,
+          responses: {},
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Create a temporary api-docs root with a single product configured.
+ *
+ * Returns the root path and a helper to write the tags.yml file.
+ */
+function createTmpRoot(): { root: string; productDir: string; specDir: string; specPath: string } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'apply-tag-test-'));
+  const productDir = path.join(root, 'influxdb3', 'core');
+  const specDir = path.join(productDir, 'v3');
+  const specPath = path.join(specDir, 'openapi.yaml');
+
+  fs.mkdirSync(specDir, { recursive: true });
+
+  // Write .config.yml — apis.data.root points to v3/openapi.yaml
+  const config = {
+    apis: {
+      data: {
+        root: 'v3/openapi.yaml',
+      },
+    },
+  };
+  fs.writeFileSync(path.join(productDir, '.config.yml'), yaml.dump(config));
+
+  return { root, productDir, specDir, specPath };
+}
+
+/**
+ * Write a YAML file from a plain object.
+ */
+function writeYaml(filePath: string, data: unknown): void {
+  fs.writeFileSync(filePath, yaml.dump(data, { lineWidth: -1 }), 'utf8');
+}
+
+/**
+ * Read and parse a YAML file.
+ */
+function readYaml<T>(filePath: string): T {
+  return yaml.load(fs.readFileSync(filePath, 'utf8')) as T;
+}
+
+/**
+ * Run the compiled script with the given root and optional product filter.
+ * Returns { stdout, stderr, exitCode }.
+ */
+function runScript(
+  root: string,
+  productFilter?: string
+): { stdout: string; stderr: string; exitCode: number } {
+  const scriptArgs = ['--root', root];
+  if (productFilter) scriptArgs.push(productFilter);
+
+  const result = spawnSync('node', [SCRIPT, ...scriptArgs], {
+    encoding: 'utf8',
+    timeout: 10_000,
+  });
+
+  return {
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    exitCode: result.status ?? 1,
+  };
+}
+
+/**
+ * Remove a temporary directory created by createTmpRoot().
+ */
+function cleanup(root: string): void {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+const failures: string[] = [];
+
+function pass(name: string): void {
+  console.log(`  PASS  ${name}`);
+  passed++;
+}
+
+function fail(name: string, reason: string): void {
+  console.log(`  FAIL  ${name}`);
+  console.log(`        ${reason}`);
+  failed++;
+  failures.push(`${name}: ${reason}`);
+}
+
+function assert(name: string, condition: boolean, reason: string): void {
+  if (condition) {
+    pass(name);
+  } else {
+    fail(name, reason);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test cases
+// ---------------------------------------------------------------------------
+
+// 1. Tag description setting
+function testDescriptionSetting(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    writeYaml(specPath, makeSpec([{ name: 'Write data' }], ['Write data']));
+    writeYaml(path.join(specDir, 'tags.yml'), {
+      tags: {
+        'Write data': { description: 'Write line protocol data to InfluxDB.' },
+      },
+    });
+
+    const { exitCode } = runScript(root, 'influxdb3/core');
+    assert('1a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
+
+    const spec = readYaml<OpenApiSpec>(specPath);
+    const tag = spec.tags?.find((t) => t.name === 'Write data');
+    assert(
+      '1b. description applied to tag',
+      tag?.description === 'Write line protocol data to InfluxDB.',
+      `description was: ${tag?.description}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 2. Tag rename — tags[] and operation.tags[]
+function testTagRename(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    writeYaml(specPath, makeSpec([{ name: 'Cache data' }], ['Cache data']));
+    writeYaml(path.join(specDir, 'tags.yml'), {
+      tags: {
+        'Cache data': { rename: 'Cache distinct values' },
+      },
+    });
+
+    const { exitCode } = runScript(root, 'influxdb3/core');
+    assert('2a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
+
+    const spec = readYaml<OpenApiSpec>(specPath);
+
+    const oldTag = spec.tags?.find((t) => t.name === 'Cache data');
+    assert('2b. old tag name gone from tags[]', !oldTag, 'old tag still present in tags[]');
+
+    const newTag = spec.tags?.find((t) => t.name === 'Cache distinct values');
+    assert('2c. new tag name in tags[]', !!newTag, 'renamed tag not found in tags[]');
+
+    const opTags = (spec.paths?.['/test']?.['get'] as { tags?: string[] })?.tags ?? [];
+    assert(
+      '2d. operation.tags[] updated',
+      opTags.includes('Cache distinct values') && !opTags.includes('Cache data'),
+      `operation tags: ${JSON.stringify(opTags)}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 3. x-related links
+function testXRelated(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    writeYaml(specPath, makeSpec([{ name: 'Write data' }], ['Write data']));
+    writeYaml(path.join(specDir, 'tags.yml'), {
+      tags: {
+        'Write data': {
+          description: 'Write data.',
+          'x-related': [{ title: 'Write data guide', href: '/influxdb3/core/write-data/' }],
+        },
+      },
+    });
+
+    const { exitCode } = runScript(root, 'influxdb3/core');
+    assert('3a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
+
+    const spec = readYaml<OpenApiSpec>(specPath);
+    const tag = spec.tags?.find((t) => t.name === 'Write data');
+    const related = tag?.['x-related'] as Array<{ title: string; href: string }> | undefined;
+    assert('3b. x-related present', Array.isArray(related) && related.length === 1, `x-related: ${JSON.stringify(related)}`);
+    assert(
+      '3c. x-related entry correct',
+      related?.[0]?.title === 'Write data guide' && related?.[0]?.href === '/influxdb3/core/write-data/',
+      `entry: ${JSON.stringify(related?.[0])}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 4. Warning: stale config reference (tag in tags.yml not in spec operations)
+function testStaleConfigWarning(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    // Spec has 'Write data' in operations but tags.yml mentions 'Ghost tag'
+    writeYaml(specPath, makeSpec([{ name: 'Write data' }], ['Write data']));
+    writeYaml(path.join(specDir, 'tags.yml'), {
+      tags: {
+        'Write data': { description: 'Write data.' },
+        'Ghost tag': { description: 'This tag does not exist in the spec.' },
+      },
+    });
+
+    const { stderr, exitCode } = runScript(root, 'influxdb3/core');
+    assert('4a. exits 0 (warnings are not errors)', exitCode === 0, `exit code was ${exitCode}`);
+    assert(
+      '4b. stale config warning emitted',
+      stderr.includes("config tag 'Ghost tag' not found in spec operations"),
+      `stderr: ${stderr}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 5. Warning: uncovered spec tag (tag in spec operations but not in tags.yml)
+function testUncoveredTagWarning(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    // Spec has 'Write data' and 'Query data'; tags.yml only covers 'Write data'
+    writeYaml(
+      specPath,
+      makeSpec([{ name: 'Write data' }, { name: 'Query data' }], ['Write data', 'Query data'])
+    );
+    writeYaml(path.join(specDir, 'tags.yml'), {
+      tags: {
+        'Write data': { description: 'Write data.' },
+      },
+    });
+
+    const { stderr, exitCode } = runScript(root, 'influxdb3/core');
+    assert('5a. exits 0 (warnings are not errors)', exitCode === 0, `exit code was ${exitCode}`);
+    assert(
+      '5b. uncovered tag warning emitted',
+      stderr.includes("spec tag 'Query data' has no config entry in tags.yml"),
+      `stderr: ${stderr}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 6. No tags.yml — silent skip, exit 0
+function testNoTagsYmlSilentSkip(): void {
+  const { root, specPath } = createTmpRoot();
+  try {
+    writeYaml(specPath, makeSpec([{ name: 'Write data' }], ['Write data']));
+    // Deliberately do NOT create tags.yml
+
+    const { stderr, exitCode } = runScript(root, 'influxdb3/core');
+    assert('6a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
+    assert(
+      '6b. no error output',
+      !stderr.includes('ERROR'),
+      `unexpected error in stderr: ${stderr}`
+    );
+  } finally {
+    cleanup(root);
+  }
+}
+
+// 7. Malformed YAML — exit 1
+function testMalformedYamlFails(): void {
+  const { root, specDir, specPath } = createTmpRoot();
+  try {
+    writeYaml(specPath, makeSpec([{ name: 'Write data' }], ['Write data']));
+    fs.writeFileSync(
+      path.join(specDir, 'tags.yml'),
+      'tags:\n  Write data:\n    description: [\n  bad yaml here',
+      'utf8'
+    );
+
+    const { exitCode } = runScript(root, 'influxdb3/core');
+    assert('7a. exits 1 on malformed YAML', exitCode === 1, `exit code was ${exitCode}`);
+  } finally {
+    cleanup(root);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run all tests
+// ---------------------------------------------------------------------------
+
+const tests: Array<[string, () => void]> = [
+  ['1. Tag description setting', testDescriptionSetting],
+  ['2. Tag rename (tags[] and operation.tags[])', testTagRename],
+  ['3. x-related links', testXRelated],
+  ['4. Warning: stale config reference', testStaleConfigWarning],
+  ['5. Warning: uncovered spec tag', testUncoveredTagWarning],
+  ['6. No tags.yml — silent skip', testNoTagsYmlSilentSkip],
+  ['7. Malformed YAML — exit 1', testMalformedYamlFails],
+];
+
+console.log('\napply-tag-config tests\n');
+
+for (const [name, fn] of tests) {
+  console.log(name);
+  try {
+    fn();
+  } catch (err) {
+    fail(name, `threw: ${(err as Error).message}`);
+  }
+}
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed`);
+
+if (failures.length > 0) {
+  console.log('\nFailed:');
+  for (const f of failures) console.log(`  - ${f}`);
+  process.exit(1);
+}