[mangglesh]

Summary

Documents Node Roles: what a resource acts as (database, cache, message queue, and more), independent of its type. This shipped across three merged PRs in nudgebee-enterprise (and a fourth, custom roles, in review) but had no page in the docs site.

Adds a new Node Roles section to Nodes and Relationships, and cross-links it from three places a reader would already be: the Node Details table, the graph overview's data table, the Attribute filter page, and NuBi's dependency-answer examples.

Covers: detected roles (from a workload's image/Helm chart) vs. user-set roles, the eleven built-in roles, typing a custom role when none fits, who can set one, and that a self-hosted VM and its matching cloud instance share one role. Also states precisely that the Attribute filter's role = X only matches tagged resources, not a managed resource whose type already implies the role (an RDS instance) — only NuBi's search covers both at once.

Type of change

• Update to existing documentation

Checklist

• I ran npm run build locally and the site builds without errors
• I ran npm run lint locally and lint passes — n/a, lint only checks .tsx; this PR is markdown only
• Internal links work; new external links open the correct page
• My commits are signed off (DCO — git commit -s)
• I read CONTRIBUTING.md

Additional notes

The Knowledge Graph page filter (node_types) and the Attribute filter are two separate mechanisms on the graph screen; only the Attribute filter reads role, and only for literally-tagged nodes. A role-aware filter that also covers type-equivalent resources in one step (what NuBi's search already does) does not exist on the graph page yet — this PR documents the product as it is today, not that gap.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the NudgeBee knowledge graph documentation to introduce and explain 'Node Roles', which describe what a resource acts as (e.g., a database or cache). The changes span multiple files, detailing how roles are detected, manually configured, filtered, and utilized by AI agents. The review comments suggest minor grammatical and phrasing enhancements to improve clarity and maintain a professional tone, such as using 'implies' instead of 'means' and clarifying the phrasing of nightly report rebuilds.

[gemini-code-assist]

The phrase 'rebuilds nightly reports' can be slightly ambiguous (is 'nightly' modifying 'rebuilds' or 'reports'?). Rearranging it to 'rebuilds reports nightly' makes the adverbial relationship clearer and improves readability. Additionally, 'whose type already means one' can be phrased more professionally as 'whose type already implies one'.

Suggested change

A node's **type** says what kind of resource it is, such as *Workload* or *ComputeInstance*. Its **role** says what it acts as: a database, a cache, a message queue, and more. A managed resource whose type already means one — an RDS instance, an ElastiCache cluster — is that role without anyone saying so. A workload, a VM or a node you declared by hand is not, until a role is set on it: a Kubernetes job that rebuilds nightly reports looks like any other workload until someone marks it as what it does.

A node's **type** says what kind of resource it is, such as *Workload* or *ComputeInstance*. Its **role** says what it acts as: a database, a cache, a message queue, and more. A managed resource whose type already implies one — an RDS instance, an ElastiCache cluster — is that role without anyone saying so. A workload, a VM or a node you declared by hand is not, until a role is set on it: a Kubernetes job that rebuilds reports nightly looks like any other workload until someone marks it as what it does.

[gemini-code-assist]

Adding the relative pronoun 'that' makes the clause 'NudgeBee treats as the same machine' much easier to read and grammatically smoother.

Suggested change

	Setting a role needs write access to the resource's account; for a node declared outside any connected account, tenant-wide access. When a resource has a matching cloud instance NudgeBee treats as the same machine, setting a role on either applies to both.
	Setting a role needs write access to the resource's account; for a node declared outside any connected account, tenant-wide access. When a resource has a matching cloud instance that NudgeBee treats as the same machine, setting a role on either applies to both.

[gemini-code-assist]

For professional tone and consistency with other pages, 'whose type already means that role' can be phrased as 'whose type already implies that role'.

[gemini-code-assist]

For professional tone and consistency with other pages, 'whose type already means that role' can be phrased as 'whose type already implies that role'.

Suggested change

	The last kind searches by [role](./nodes-and-relationships.md#node-roles) — what a resource acts as — so it covers both a managed resource whose type already means that role (an RDS instance) and a workload or VM someone has tagged, in one answer.
	The last kind searches by [role](./nodes-and-relationships.md#node-roles) — what a resource acts as — so it covers both a managed resource whose type already implies that role (an RDS instance) and a workload or VM someone has tagged, in one answer.