docs(roles-and-permissions): add Viewer troubleshooting for source-creation access error

[george-dilthey]

What changed

Added a "Troubleshooting" subsection to the Viewers section of docs/roles-and-permissions.md explaining what causes the "You do not have the proper access to this workspace" error when a Viewer tries to add a source like Find People or Find Companies, and how to resolve it.

Why

Intercom conversation #215475099500798: Luke Gidus (Airwallex, Enterprise plan, Viewer role) reported seeing "You do not have the proper access to this workspace" when trying to use Find People. Clay support agent Bo diagnosed the root cause (Viewer role can't create new tables/sources) and provided the fix (ask admin to upgrade role or add as workbook collaborator). The existing doc already documents that Viewers can't create tables, but it makes no connection to the specific error message Viewers see when using sources like Find People, and gives no troubleshooting steps.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475099500798
• Slack thread (support channel ent-airwallex): https://clay-hq.slack.com/archives/C078FS8JYK0/p1784135848717649
• Verifier sub-agent confirmed PASS: apps/api/v3/tables/endpoints/sources.endpoints.ts:242-245 (createSourceCore calls checkCanCreateSourceForWorkspace with empty destinationTableIds), apps/api/v3/workspaces/services/workspace-abilities.service.ts:68-81 (WorkspaceViewer gets only Read ability, not CreateResource), and apps/api/v3/tables/routes/table-routes-common-utils.ts:211 (exact "You do not have the proper access to this workspace" error string).

Uncertainties

None — the error message and the Viewer role restriction are confirmed by the verifier at specific file:line citations. The change is narrow and limited to what was verified.

Related observations

• PR docs(audiences): document Editor vs Admin role permissions in Audiences #1632 is also open on docs/roles-and-permissions.md and adds content about Audiences access by role — a different section and topic. Both PRs touch the same file but in non-overlapping sections; a reviewer should reconcile the two at merge time.
• The support agent initially said "running an existing source is allowed at lower access levels." The verifier confirmed this is FAIL: Viewers can only run sources on tables they own, not on arbitrary tables. I did not document this nuance — only the confirmed PASS claim (Viewer role blocks source creation because it requires CreateResource which Viewers don't have).

Closes DOC-1243

[linear-code]

DOC-1243