docs: improve meta directive docs and product update (#6828)

Author: jdolle

packages/web/docs/src/app/product-updates/(posts)/2025-03-08-metadata/page.mdx

@@ -26,41 +26,41 @@ extend schema @link(url: "https://specs.graphql-hive.com/hive/v1.0", import: ["@
 
 Metadata is useful for a variety of cases:
 
-- Indicating granular ownership e.g. `owner: "console-team"`
-- Adding contact information e.g. `contact: "#hive-channel"`
-- Defining field importance e.g. `priority: "tier-1"`
-- Defining domains e.g. `domain: "users"`
+- Indicating granular ownership e.g. `@meta(name: "owner", content: "console-team")`
+- Adding contact information e.g. `@meta(name: "contact", content: "#hive-channel")`
+- Defining field importance e.g. `@meta(name: "priority", content: "tier-1")`
+- Defining domains e.g. `@meta(name: "domain", content: "users")`
 
 ... and more.
 
-Currently, metadata can be viewed from Hive’s explorer page and can be used to filter the explorer
-view. And we expect there will be even more features built around this metadata in the future as
-Hive continues to expand.
-
-A full example schema of using metadata would look like:
+Putting it all together, an example schema using Hive's metadata might look like:
 
 ```graphql
 extend schema
   @link(url: "https://specs.apollo.dev/link/v1.0")
   @link(url: "https://specs.apollo.dev/federation/v2.3")
   @link(url: "https://specs.graphql-hive.com/hive/v1.0", import: ["@meta"])
-  @meta(name: "owner", content: "users-team")
+  @meta(name: "owner", content: "[email protected]")
 
 directive @meta(
   name: String!
   content: String!
 ) repeatable on SCHEMA | OBJECT | INTERFACE | FIELD_DEFINITION
 
 type Query {
-  me: User @meta(name: "priority", content: "tier-1")
+  user: User @meta(name: "domain", content: "accounts") @meta(name: "priority", content: "tier-1")
 }
 
 type User {
   id: ID!
-  name: String!
+  ssn: String @meta(name: "classification", content: "pii")
 }
 ```
 
+Currently, metadata can be viewed from Hive’s explorer page and can be used to filter the explorer
+view. And we expect there will be even more features built around this metadata in the future as
+Hive continues to expand.
+
 ---
 
 [Learn more in the updated documentation](/docs/specs/link-specifications)

packages/web/docs/src/content/specs/link-specifications.mdx

@@ -85,13 +85,36 @@ import explorerMetadataFilterImage from '../../../public/docs/pages/specs/link-s
 
 #### Usage
 
+```graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/link/v1.0")
+  @link(url: "https://specs.apollo.dev/federation/v2.3")
+  @link(url: "https://specs.graphql-hive.com/hive/v1.0", import: ["@meta"])
+  @meta(name: "owner", content: "[email protected]")
+
+directive @meta(
+  name: String!
+  content: String!
+) repeatable on SCHEMA | OBJECT | INTERFACE | FIELD_DEFINITION
+
+type Query {
+  user: User @meta(name: "domain", content: "accounts") @meta(name: "priority", content: "tier-1")
+}
+
+type User {
+  id: ID!
+  ssn: String @meta(name: "classification", content: "pii")
+}
+```
+
 `@meta` can be applied to schemas, types, interfaces, and fields. A field's metadata is a union of
 all applied metadata. This is applied using the following rules:
 
 1. meta on a schema applies to every field in the schema.
 2. meta on a type applies to every field in that exact type.
 3. meta on an interface applies to every field in that interface on every implemented type.
 4. meta on a field applies only to that field for that type.
+5. meta is additive and will not override other applied or repeated directives.
 
 </Tabs.Tab>
 </Tabs>