Tag articles with roles

Roles are how you partition your help center for different audiences. A SaaS product with developer docs, admin docs, and end-user docs lives more cleanly when each audience sees only their content. Roles make that possible.

Roles are visibility tags — they control what shows up when a customer browses the public help center. They don’t bias AI retrieval. AI agents (Capabilities, Sidekick, Web Chat, voice) retrieve from every published article regardless of role tagging. Roles answer “who should see this when browsing”, not “which articles should the AI prefer.”

When to use roles

• Your help center has clearly distinct audiences (developers vs. end users, admins vs. agents, sales reps vs. customers).
• You want to keep one Knowledge Base instead of running multiple help centers.
• The audiences would be confused by each other’s content (a developer doesn’t want to wade through “How to update your billing address”; an end user doesn’t want to see an OAuth scope reference).

If your audiences overlap heavily, skip roles. The simpler the navigation, the better.

Create a role

1. Go to Settings → Knowledge → Roles.
2. Click Add role.
3. Fill in:
   Name — what visitors see in the role switcher. “Developer”, “End user”, “Admin”.
   Slug — used in URLs (/role/developer). Auto-generated.
   Description — optional. Shown in the role grid block on the public site.
   Icon — optional. Renders in the role grid.
4. Save.

The role exists but no articles are tagged with it yet — so it’s effectively empty until you start tagging.

Tag an article with one or more roles

1. Open the article.
2. In the metadata panel, find Roles.
3. Click to add roles. An article can be tagged with multiple roles — useful when an article applies to several audiences.
4. Save.

An article tagged with developer and admin is visible when either role is selected on the public site. An article with no roles is visible to everyone.

How visitors choose a role

Two patterns:

• Role grid / role bar block — Visitors land on a help center that shows a row or grid of role tiles (“I’m a developer”, “I’m an end user”). They click their role and the help center filters to that role’s articles.
• Direct role URL — A visitor lands on /role/developer (linked from your product or docs). The help center is pre-filtered.

Both are configured in the layout builder. Drop a Role Grid or Role Bar block onto the homepage; or link directly to /role/<slug> from your product UI.

What visitors see when filtered

With a role selected, the public help center shows:

• Articles tagged with that role.
• Articles tagged with no role (universal articles).
• Categories that have at least one matching article.

Articles tagged with only other roles are hidden — they aren’t searchable, aren’t listed, and direct links to them resolve normally (so external links don’t break, but in-site navigation excludes them).

Visitors not filtered to any role see every published article that doesn’t have role tagging restrictions, plus role-tagged articles that don’t have a role-filter UI hiding them.

What roles don’t do

• They don’t replace authentication. Anyone can switch to any role on the public site. Roles are about navigation, not access control. If you have content that requires authentication, gate it elsewhere.
• They don’t change AI retrieval. Capabilities, Sidekick, Web Chat, and voice all retrieve from every published article regardless of role. An article tagged admin will still be cited by AI when it’s the most relevant answer to a customer’s question.
• They don’t apply to the Handbook. The Handbook has its own access-rule system. See What is the Handbook?.

Bulk-tagging articles with roles

Bulk role assignment isn’t available in the bulk-edit UI. For now, you can:

• Tag articles individually as you write them.
• Push articles via the external KB API, which accepts roles in the article frontmatter on the internal API path. Note: the v1 surface doesn’t yet expose role tagging, so this path requires a Supabase session, not a tenant API key.

If you have a large set of existing articles to tag in one go, the fastest path today is the in-app editor article-by-article.

Common patterns

• Three-role help centers. “End user”, “Admin”, “Developer” — the most common SaaS pattern. End-user articles untagged by default (so they’re universal); admin and developer articles tagged.
• Internal vs. external. “Customer”, “Reseller”, “Partner” — different audiences with different terminology.
• Hide internal content from a public role-grid. Tag an article with internal-team only; visitors with no role filter still won’t see it because the universal pool excludes role-tagged articles only when a role filter is active.

A reminder

Roles are visibility, not retrieval bias. If you find yourself thinking “let’s tag this with developer so the AI prefers it” — that’s not what roles do. The AI retrieves on relevance, not role overlap. If retrieval feels off for a specific audience, the right fix is better article content, better keywords, or splitting the article — not role tagging.