Contextual help and role audit

Outcome

Product help links lead each project role to a public, bilingual page that either describes an allowed task or states the permission boundary and safe handoff. The public product never links to the protected Operator Runbook.

Verified: 22 October 2026 against apps/web/src/lib/docs.ts, settings tab visibility, the current EN/RU source tree, and the web link tests.

Audited links

Product surface	Visible audience	Documentation target	Target audience	Result
Dashboard activation checklist	All project roles	Getting started	All project roles	Safe read/action path
Approvals page	All project roles	Approvals	All project roles; resolution is explicitly admin/owner	Missing controls have a safe administrator handoff
Reports page	All project roles	Reports and Graph Health	All project roles	Safe read path
Dashboard Graph Health card	All project roles	Reports and Graph Health	All project roles	Safe read path
Connectors header	All project roles that can open the screen	Connection setup	admin/owner	Page states the required role before setup and tells other roles to hand off without sharing credentials
Connector failure banner	All project roles that can inspect status	Troubleshooting	All project roles	Symptom-first, no privileged workaround
Settings → MCP	All project roles	MCP setup	All project roles; API-key creation is handed to an administrator	Viewer read-only boundary is explicit
Settings → Members	All project roles	Role permissions	All project roles	Read-only role table; no invitation instruction for a member/viewer
Header Help menu → Documentation	All project roles	Documentation home	All project roles	Public landing page; menu is hidden when the docs origin is unreachable
Header Help menu → Merge request review guide	All project roles	Merge request review	All project roles; settings changes are admin	Read path; the settings table states the admin boundary
Header Help menu → First review in five minutes	All project roles	Your first review in five minutes	admin/owner	Page states the required role before setup and tells other roles to hand off without sharing credentials

The application uses the English canonical path. The Material language switcher opens the matching Russian page. Every target in DOCS_PATHS has both .md and .ru.md sources.

Operator boundary

Operator pages contain deployment, migration, backup, incident, and protected environment procedures. They are excluded from the public MkDocs config and public container. No value in DOCS_PATHS may begin with operator/; docsUrl() also rejects such a target at runtime after an unsafe cast.

Operators reach those pages only through the authenticated internal documentation build. Product roles are never sent from the public UI to GitLab Pages access control.

What a safe target must contain

For an action unavailable to every viewer of the source screen, the target page must state:

1. the minimum role before the first action;
2. what a lower role may safely inspect;
3. whom to contact or what information to hand off;
4. that users must not share sessions, tokens, or connector credentials;
5. a non-privileged verification or troubleshooting path where possible.

A link is not acceptable when it is dead, opens Operator content, assumes hidden controls exist, or tells a lower role to bypass authorization.

Automated checks

The web test checks that every contextual target:

• stays outside operator/;
• has English and Russian source files;
• has an explicit audience entry;
• opens with safe external-link attributes.

Run:

npm --prefix apps/web test -- docs-link.test.tsx
make docs-build
make docs-build-internal

Strict MkDocs builds check links inside the target pages. When adding contextual help, update DOCS_PATHS, DOCS_AUDIENCES, this table, and both language versions in the same merge request.