Update collaboration/comments.mdx based on latest features (#868)

Co-authored-by: hasura-bot <[email protected]>
Co-authored-by: Rob Dominguez <[email protected]>

docs/collaboration/comment.mdx

@@ -24,8 +24,7 @@ effectively about their API design and implementation.
 
 :::tip Getting Access
 
-This feature is currently in limited access and only available for Hasura Cloud projects. To get access, please fill out
-this [form](https://forms.gle/tudE2jzD7get5iJF7).
+This feature is available for all users on [Base and Advanced plans](https://hasura.io/pricing).
 
 :::
 
@@ -41,85 +40,87 @@ You can add comments on various objects from your metadata.
 
 ## Commenting areas
 
-You can add comments to the following areas:
-
 ### Explorer Tab
 
-#### Supergraph Page
-
-<Thumbnail src="/img/get-started/comments_supergraph.png" alt="Hover over fields to add comments" width="800" />
-<br />
+The **Explorer Tab** is the primary interface where users interact with the API metadata, making it a crucial place for
+collaboration. Comments here enable API producers and consumers to discuss design decisions, clarify data models, and
+suggest improvements directly on specific metadata elements.
+
+- **Supergraph Page** – Comment on the overall schema design, structure, and implementation details of the supergraph.
+- **Subgraph Page** – Provide feedback on individual subgraphs, ensuring alignment with the larger supergraph design.
+- **Models → General**
+  - **Description** – Clarify the model’s purpose and usage for better documentation.
+  - **Signature** – Discuss function signatures, return types, and argument structures.
+  - **GraphQL Root Fields** – Suggest improvements or changes to the root field definitions.
+- **Models → Fields & Relationships**
+  - **Output Fields** – Ask questions or provide insights on field usage and expected data.
+  - **Arguments** – Discuss argument types, required vs. optional parameters, and potential defaults.
+  - **Relationships** – Ensure relationships between models are well-defined and documented.
+- **Models → Permissions**
+  - **Role** – Comment on role-based access control settings.
+  - **Read / Create / Update / Delete** – Discuss permission settings for different CRUD operations.
+
+This feature is especially useful for teams working on large-scale API projects, as it ensures everyone stays aligned on
+API structure and permissions.
+
+<Thumbnail src="/img/get-started/comments_explorer.png" alt="Comments on Explorer" width="800" />
 
-#### Subgraph Page
+---
 
-<Thumbnail src="/img/get-started/comments_subgraph.png" alt="Hover over fields to add comments" width="500" />
-<br />
+### GraphiQL Tab
 
-#### Models --> General
+The **GraphiQL Tab** is where users can interactively query the API and test GraphQL operations. Commenting here allows
+for real-time feedback on API responses, query structures, and potential performance optimizations.
 
-- Description
-- Signature
-- GraphQL root fields
+- Discuss unexpected query results and suggest potential schema modifications.
+- Collaborate on best practices for query structuring and field selection.
+- Provide feedback on performance concerns, such as response times and pagination strategies.
+- Leave notes on commonly used queries to improve team-wide API consistency.
 
-<Thumbnail src="/img/get-started/console_comment-general.png" alt="Comments on General" width="1000" />
+By adding comments directly in GraphiQL, teams can streamline debugging and optimize API queries collaboratively.
 
-#### Models --> Fields & Relationships
+<Thumbnail src="/img/get-started/comments_graphiql.png" alt="Comments on GraphiQL" width="800" />
 
-- Output fields
-- Arguments
-- Relationships
+---
 
-<Thumbnail
-  src="/img/get-started/console_comment-fields-and-relationships.png"
-  alt="Comments on Fields and Relationships"
-  width="1000"
-/>
+### Insights Tab
 
-#### Models --> Permissions
+The **Insights Tab** provides performance metrics, traces, and reports about API usage. Commenting here helps teams
+analyze and discuss API behavior, identify bottlenecks, and track improvements over time.
 
-- Role
-- Read
-- Create
-- Update
-- Delete
+- **Performance** – Leave feedback on latency, throughput, and error rates.
+- **Platform Report** – Discuss API usage patterns and suggest improvements.
+- **Traces** – Analyze request traces and collaborate on optimizing execution paths.
 
-<Thumbnail src="/img/get-started/console_comment-permissions.png" alt="Comments on Permissions" width="1000" />
-<br />
-<br />
+This feature is valuable for DevOps, backend engineers, and API consumers looking to enhance API efficiency.
 
-### GraphiQL Tab
+<Thumbnail src="/img/get-started/comments_insights.png" alt="Comments on Insights" width="800" />
 
-<Thumbnail src="/img/get-started/comments_graphql.png" alt="Alt text" />
-<br />
-<br />
+---
 
-### Insights Tab
+### Builds Tab
 
-<Thumbnail src="/img/get-started/comments_insights.png" alt="Comments on Permissions" width="1000" />
+The **Builds Tab** allows teams to track and validate schema changes across supergraph, subgraph, and connector builds.
+Commenting in this area helps teams coordinate schema evolution and avoid breaking changes.
 
-<br />
-<br />
+- **Supergraph Builds** – Discuss schema changes at the supergraph level and their impact on consumers.
+- **Subgraph Builds** – Leave comments about specific subgraph updates and dependencies.
+- **Connector Builds** – Provide feedback on connector integrations and compatibility.
+- **Schema Diff** – Highlight breaking changes or inconsistencies between schema versions.
 
-### Builds Tab
+By facilitating discussions on builds, teams can ensure smooth API evolution and prevent unexpected failures.
 
-<Thumbnail src="/img/get-started/comments_builds.png" alt="Comments on Permissions" width="1000" />
+<Thumbnail src="/img/get-started/comments_builds.png" alt="Comments on Builds" width="800" />
 
 ## Notifications
 
-To ensure effective collaboration, you can tag subgraph collaborators in your comments:
-
-1. Type `@` in your comment.
-2. Select the collaborator you want to notify.
-
-Tagged collaborators will receive an email with your comments and a notification on the notification hub on the console,
-keeping them informed of any discussions or questions.
+In-app notifications show new comments made on your project.
 
 The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see
-all the comments where you are tagged in one place. The messages will be grouped based on the underlying commenting
-thread. You can click on a particular comment (deep linking) and go to the original thread on the console. You can also
-delete notifications from that menu.
+all the comments where you are tagged in one place. You can click on a particular comment (deep linking) and go to the
+original thread on the console. You can also delete notifications from that menu.
 
-{/* <Thumbnail src="/img/get-started/comments_notification.png" alt="Alt text" width="100" height="100" /> */}
+{/* <Thumbnail src="/img/get-started/comments_notification.png" alt="Notifications" width="100" height="100" /> */}
 ![Alt text](/img/get-started/comments_notification.png)
 
 <br />
@@ -136,7 +137,8 @@ You can learn how to invite collaborators [here](/project-configuration/project-
 The feature is in early access and has known limitations, which are in our backlog. Let us know if you would like to
 prioritize any specific functionality.
 
-1. Notification Email on Resolving comments.
-2. Ability to auto notify subgraph admin and developers.
-3. History Tab for comments.
-4. Figma Style (Canvas) Commenting.
+1. Tagging users on comments
+2. Resolving comments
+3. Email notifications
+4. Ability to auto notify subgraph admin and developers.
+5. History Tab for comments.