docs: explain use cases for --metadata vs @meta (#6878)

Author: jdolle

packages/web/docs/src/content/api-reference/cli.mdx

@@ -234,8 +234,17 @@ hive schema:publish \
 
 #### Metadata
 
-You can attach metadata to your schema publication. Hive metadata published to Hive must be a valid
-JSON, and limited to `25MB`.
+<Callout>
+  For most cases, it's recommended to add metadata directly to your schema with the [@meta Link
+  Specification](/docs/specs/link-specifications#meta) instead of using `--metadata`. Directives
+  allow you to enhance specific parts of your schema with this important information, which can be
+  especially useful for large projects with multiple owners.
+</Callout>
+
+You can attach metadata to your schema publication. Metadata files published to Hive must be valid
+JSON and are limited to `25MB`. This metadata is not exposed in the Hive UI, but it can be useful
+for storing JSON configuration files for services, such as for
+[GraphQL Mesh](https://the-guild.dev/graphql/mesh/docs/config-reference).
 
 To attach metadata to your published schema, you can use `--metadata` flag when publishing.
 
@@ -262,6 +271,7 @@ hive schema:publish \
 **Further reading:**
 
 - [Fetching Hive Metadata from the CDN](/docs/high-availability-cdn)
+- [Using the @meta Link Specification](/docs/specs/link-specifications#meta)
 
 ### Check a Schema