2. Roles and permissions#
| Role | Can |
|---|---|
Viewer (kb:read) | Browse and Ask within their group visibility |
Contributor (kb:write) | + upload, crawl, curate, tag |
Admin (kb:admin) | + members, groups, settings, deletion, API keys |
Groups are the visibility system. Adding a document to a group makes it visible only to members of that group (and admins). A document in no group is visible to the whole workspace. This is enforced everywhere: the documents table, search, Ask answers, the knowledge graph, analytics — and your connected agents (§9). Tags never affect visibility — they are free-text organization and retrieval hints only.
Developer note: the storage layer has a legacy split: group visibility for curated concepts is represented by group-name values in kb_concepts.tags, while raw documents use kb_documents.groups for visibility and kb_documents.tags for free-text labels. Workspace, API, graph, analytics, and agent flows must keep concept filters on tags and document filters on groups; regression tests pin this contract.
Agent tokens carry their own scope, separate from your role. When you connect an agent (§9) you mint a personal token as Read (kb:read), Read + remember (kb:read + kb:remember — drafts reviewable notes), or Read + author (kb:read + kb:author — writes directly into shared, authoritative team knowledge, cited to you, §9). Minting any of these only requires the Viewer role — kb:author/kb:remember are token scopes, not workspace roles, so even a Viewer can hold a "Read + author" token.