feat(enterprise): document influx-meta CLI and cleanup-shards command

PLAN.md

@@ -497,77 +497,6 @@ time                bind  hostname    user userQueryRespBytes
 
 ***
 
-## PR #6950 link check fixes
-
-PR link check found 28 broken fragment links (first run) + 13 additional (second run). All resolved.
-
-### Fixed (in this branch, first pass)
-
-| Broken link | Fix | File |
-|---|---|---|
-| `config-data-nodes/#https-insecure-certificate` | Added `#### https-insecure-certificate` heading to `[cluster]` section | `config-data-nodes.md` |
-| `config-data-nodes/#https-insecure-certificate-1` | Added `#### https-insecure-certificate` heading to `[http]` section (Hugo generates `-1` suffix) | `config-data-nodes.md` |
-| `config-data-nodes/#advanced-expiration` | Added `#### advanced-expiration` heading to `[tls]` section | `config-data-nodes.md` |
-| `backup/#backup-compression` | Added `-gzipBlockCount`, `-gzipBlockSize`, `-gzipCompressionLevel` to flags table; changed release notes link to `backup/#flags` | `backup.md`, `release-notes.md` |
-
-### Fixed (second pass — CI run #23826485679)
-
-| Broken link | Fix | File |
-|---|---|---|
-| `github.com/influxdb/influxdb/issues/4275` (404) | Wrong GitHub org: `influxdb` → `influxdata` | `manage-database.md` (enterprise + OSS) |
-| `wiki.mozilla.org/...#Modern_compatibility` (fragment gone) | Removed `#Modern_compatibility` fragment | `config.md` (OSS) |
-| `config-data-nodes/#pprof-enabled-1` | Only one `pprof-enabled` heading exists → `#pprof-enabled` | `release-notes.md` |
-| `authentication_and_authorization/#authenticate-requests` | Old page is now an alias → rewrote to `configure/security/authentication/` | `query_language/_index.md` |
-| `authentication_and_authorization/#user-types-and-privileges` | → `manage/users-and-permissions/authorization-influxql/#non-admin-users` | `query_language/_index.md` |
-| `authentication_and_authorization/#user-management-commands` | → `manage/users-and-permissions/authorization-influxql/#user-management-commands` | `query_language/_index.md` |
-| `backup-and-restore/#example` | Heading is "Example: export and import..." → `#example-export-and-import-for-disaster-recovery` | `backup-and-restore.md` |
-| `backup-and-restore/#perform-a-metastore-only-backup` | Heading says "metadata" not "metastore" → `#perform-a-metadata-only-backup` | `backup-and-restore.md` |
-| `backup-and-restore/#restore-from-a-full-backup` | Heading is "Restore from a `-full` backup" → `#restore-from-a--full-backup` | `backup-and-restore.md` |
-| `replacing-nodes/#replace-a-data-node-in-an-influxdb-enterprise-cluster` | Heading uses plural "nodes" → `#replace-data-nodes-in-an-influxdb-enterprise-cluster` | `replacing-nodes.md` |
-| `replacing-nodes/#31-kill-the-meta-process-on-the-leader-node` | Heading `3.1 -` produced triple-hyphen slug; changed heading to `3.1.` format | `replacing-nodes.md` |
-| `replacing-nodes/#32-remove-and-replace-the-old-leader-node` | Same: `3.2 -` → `3.2.` format | `replacing-nodes.md` |
-| `replacing-nodes/#2-1-provision-a-new-meta-node` | Hugo removes `.` without hyphen → `#21-provision-a-new-meta-node` | `replacing-nodes.md` |
-
-### Also fixed (pre-existing broken links, all resolved)
-
-#### ~~Old path `/administration/configuration/` (should be `/configure/config-data-nodes/`)~~ FIXED
-
-Source: `release-notes.md` (old release entries) — paths updated to `/configure/config-data-nodes/`.
-
-#### ~~Old path `/administration/config-data-nodes` (missing `/configure/`)~~ FIXED
-
-All occurrences in `upgrading.md`, `replacing-nodes.md`, `config-meta-nodes.md` updated to `/configure/config-data-nodes/` with correct fragments.
-
-#### ~~Old path `/administration/config-meta-nodes` + default value suffix~~ FIXED
-
-`influxd-ctl/_index.md` updated to `configure/config-meta-nodes/#auth-enabled`.
-
-#### ~~Fragment includes default value~~ FIXED
-
-- `release-notes.md`: `#termination-query-log` → `#termination-query-log--false`; `#max-values-per-tag-100000` → `#max-values-per-tag`
-
-#### ~~Self-reference `#meta-internal-shared-secret` in config-meta-nodes.md~~ FIXED
-
-Changed to `#internal-shared-secret` (2 occurrences).
-
-#### ~~Missing/wrong headings in spec.md~~ FIXED
-
-- Removed ToC entry for non-existent `#query-engine-internals`
-- `#execution-time` → `#execution_time`; `#planning-time` → `#planning_time`
-- `#understanding-iterators` / `#understanding-cursors` → replaced with links to existing `#iterator-type` / `#cursor-type` sections
-
-#### ~~Redirected/wrong paths~~ FIXED
-
-- `authentication_and_authorization/#set-up-authentication` → `configure/security/authentication/#enable-authentication` (in `tools/api.md`, `query_language/_index.md`)
-- `query_management/#list-currently-running-queries-with-show-queries` → added `influxql_query_management/` to path (in `spec.md`)
-- `influxql_query_management.md`: fixed `coordinator` link text → `[cluster]`, path → `configure/config-data-nodes/#cluster`
-
-#### ~~Glossary and misc~~ FIXED
-
-- `glossary/#replication-factor` → `#replication-factor-rf` in 10 enterprise files (OSS refs left as-is — correct there)
-- `backup-and-restore/#restore` → `#restore-utility` in `migration.md`
-- Mozilla wiki `#Modern_compatibility` fragment removed from external link in `config-data-nodes.md`
-
 ## Notes
 
 - The OSS and Enterprise `api.md` files are independent (no shared `source` frontmatter) — each needs separate edits.

content/enterprise_influxdb/v1/tools/influx-meta/_index.md

@@ -0,0 +1,56 @@
+---
+title: influx-meta CLI
+description: >
+  Use the `influx-meta` CLI to export and edit metadata in a live InfluxDB
+  Enterprise v1 cluster.
+draft: true
+cascade:
+  draft: true
+menu:
+  enterprise_influxdb_v1:
+    weight: 12
+    parent: Tools
+    name: influx-meta
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta` CLI lets you export and edit metadata in a live InfluxDB
+Enterprise cluster.
+
+> [!Caution]
+> Use `influx-meta` with great caution.
+> Commands in this tool directly modify cluster metadata and can cause data loss
+> if used incorrectly.
+> Before running any command, ensure no concurrent metadata-modifying operations
+> are in progress (such as anti-entropy repairs or `influxd-ctl` operations).
+
+## Usage
+
+```
+influx-meta <command> [flags]
+```
+
+## Commands
+
+| Command | Description |
+| :------ | :---------- |
+| [cleanup-shards](/enterprise_influxdb/v1/tools/influx-meta/cleanup-shards/) | Clean up orphaned shards and empty shard groups in a live cluster. _v1.12.3+_ |
+| [convert](/enterprise_influxdb/v1/tools/influx-meta/convert/) | Convert metadata snapshots between binary and JSON. _v1.12.0+_ |
+| [export](/enterprise_influxdb/v1/tools/influx-meta/export/) | Export metadata from a live cluster to JSON. _v1.12.0+_ |
+| [fix-shard-owners](/enterprise_influxdb/v1/tools/influx-meta/fix-shard-owners/) | Remove invalid shard owners. _v1.12.0+_ |
+| [import](/enterprise_influxdb/v1/tools/influx-meta/import/) | Import metadata from JSON to a live cluster. _v1.12.0+_ |
+| [make-node-active](/enterprise_influxdb/v1/tools/influx-meta/make-node-active/) | Put a data node in active mode. _v1.12.0+_ |
+| [make-node-passive](/enterprise_influxdb/v1/tools/influx-meta/make-node-passive/) | Put a data node in passive mode. _v1.12.0+_ |
+| [renumber-shard-groups](/enterprise_influxdb/v1/tools/influx-meta/renumber-shard-groups/) | Renumber shard groups starting at 1. _v1.12.0+_ |
+| [set-shard-group](/enterprise_influxdb/v1/tools/influx-meta/set-shard-group/) | Set the next shard group ID. _v1.12.0+_ |
+
+## Global flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |

content/enterprise_influxdb/v1/tools/influx-meta/cleanup-shards.md

@@ -0,0 +1,82 @@
+---
+title: influx-meta cleanup-shards
+description: >
+  The `influx-meta cleanup-shards` command removes orphaned shards and empty
+  shard groups from the metadata of a live InfluxDB Enterprise cluster.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.3+
+related:
+  - /enterprise_influxdb/v1/tools/influxd-ctl/show-shards/
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta cleanup-shards` command removes orphaned shards and empty
+shard groups from the metadata of a live InfluxDB Enterprise cluster.
+
+The command performs the following operations:
+
+1. Identifies shards with no owners (orphaned shards).
+2. Removes orphaned shards from metadata.
+3. Removes shard groups that contain no shards after cleanup.
+4. Displays a summary of proposed changes for confirmation before committing.
+
+If the cluster metadata changes while the command runs (for example, from
+another operation), the command fails safely without modifying metadata.
+
+## Prerequisites
+
+Before running `cleanup-shards`:
+
+- Disable [anti-entropy](/enterprise_influxdb/v1/administration/configure/anti-entropy/)
+  to prevent concurrent metadata modifications.
+- Stop any `influxd-ctl` operations that modify metadata.
+- Run [`SHOW SHARDS`](/enterprise_influxdb/v1/query_language/spec/#show-shards)
+  and verify no shards are within 30 minutes of their end time.
+
+## Usage
+
+```sh
+influx-meta cleanup-shards [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |
+
+## Output
+
+The command displays a table of shards that will be removed:
+
+```
+ID    Database    RP       Shard Group    Start                  End
+--    --------    --       -----------    -----                  ---
+42    mydb        autogen  12             2023-01-01T00:00:00Z   2023-01-08T00:00:00Z
+55    mydb        autogen  15             2023-02-01T00:00:00Z   2023-02-08T00:00:00Z
+```
+
+After displaying the summary, the command prompts for confirmation before
+committing the changes.
+
+## Examples
+
+### Clean up shards on a local meta node
+
+```sh
+influx-meta cleanup-shards
+```
+
+### Clean up shards on a remote meta node
+
+```sh
+influx-meta cleanup-shards --host meta-node-01:8091
+```

content/enterprise_influxdb/v1/tools/influx-meta/convert.md

@@ -0,0 +1,32 @@
+---
+title: influx-meta convert
+description: >
+  The `influx-meta convert` command converts metadata snapshots between binary
+  and JSON formats.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.0+
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta convert` command converts metadata snapshots between binary
+and JSON formats.
+
+## Usage
+
+```sh
+influx-meta convert [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |

content/enterprise_influxdb/v1/tools/influx-meta/export.md

@@ -0,0 +1,32 @@
+---
+title: influx-meta export
+description: >
+  The `influx-meta export` command exports metadata from a live InfluxDB
+  Enterprise cluster to JSON.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.0+
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta export` command exports metadata from a live InfluxDB
+Enterprise cluster to JSON.
+
+## Usage
+
+```sh
+influx-meta export [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |

content/enterprise_influxdb/v1/tools/influx-meta/fix-shard-owners.md

@@ -0,0 +1,32 @@
+---
+title: influx-meta fix-shard-owners
+description: >
+  The `influx-meta fix-shard-owners` command removes invalid shard owners from
+  cluster metadata.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.0+
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta fix-shard-owners` command removes invalid shard owners from
+cluster metadata.
+
+## Usage
+
+```sh
+influx-meta fix-shard-owners [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |

content/enterprise_influxdb/v1/tools/influx-meta/import.md

@@ -0,0 +1,32 @@
+---
+title: influx-meta import
+description: >
+  The `influx-meta import` command imports metadata from JSON to a live InfluxDB
+  Enterprise cluster.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.0+
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta import` command imports metadata from JSON to a live InfluxDB
+Enterprise cluster.
+
+## Usage
+
+```sh
+influx-meta import [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |

content/enterprise_influxdb/v1/tools/influx-meta/make-node-active.md

@@ -0,0 +1,30 @@
+---
+title: influx-meta make-node-active
+description: >
+  The `influx-meta make-node-active` command puts a data node in active mode.
+menu:
+  enterprise_influxdb_v1:
+    parent: influx-meta
+weight: 201
+metadata: v1.12.0+
+---
+
+<!-- DRAFT — DO NOT PUBLISH.
+     influx-meta is an internal InfluxData engineering/support tool, not shipped
+     in the InfluxDB Enterprise release. Keep draft: true on this page.
+     See https://github.com/influxdata/docs-v2/issues/6842 for context. -->
+
+The `influx-meta make-node-active` command puts a data node in active mode.
+
+## Usage
+
+```sh
+influx-meta make-node-active [flags]
+```
+
+## Flags
+
+| Flag | Description |
+| :--- | :---------- |
+| `--host` | Address and port of the meta node _(default: `localhost:8091`)_ |
+| `--config` | Config file path _(default: `$HOME/.influx-meta.yaml`)_ |