[guides] Document per-project roles

docs/guides/permissions-roles.md

@@ -187,6 +187,44 @@ curl -X PUT "http://api.example.com/data/persons/a24a6ea4-ce75-4665-a070-5745308
 ```
 :::
 
+## Per-project roles
+
+A person has one global role, but can be given a different role on a
+specific production: someone working as an artist on most projects can act
+as a supervisor on one of them. The project role only applies inside that
+production; the global role keeps applying everywhere else.
+
+Set the role when adding the person to the team, or change it later:
+
+::: code-group
+```python [Python]
+gazu.project.add_person_to_team(project, person, role="supervisor")
+
+gazu.project.update_team_member_role(project, person, "manager")
+
+# Back to the global role
+gazu.project.update_team_member_role(project, person, None)
+```
+```bash [cURL]
+curl -X PUT "http://api.example.com/data/projects/a24a6ea4-ce75-4665-a070-57453082c25/team/b35b7fb5-df86-5776-b181-68564193d36" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"role": "supervisor"}'
+```
+:::
+
+Rules to know:
+
+* Assignable project roles: `user`, `supervisor`, `manager`, `client` and
+  `vendor`. `admin` stays a global-only role and is rejected with a 400.
+* A person without an explicit project role inherits their global role, and
+  keeps following it when the global role changes later.
+* Changing a project role requires manager rights on that project: a
+  per-project manager can manage the roles of their own production.
+* The team listing exposes the explicit role of each member under the
+  `project_role` key (`None` means the global role applies). The update
+  response returns the same value under a `role` key.
+
 ## Check a person's role
 
 ::: code-group

docs/guides/team-management.md

@@ -111,6 +111,9 @@ person = gazu.person.get_person_by_desktop_login("john.doe")
 
 ### Get team for a project
 
+Each member dict carries a `project_role` key: the role explicitly set for
+this production, or `None` when the person's global role applies.
+
 ::: code-group
 ```python [Python]
 team = gazu.project.get_team(project)
@@ -119,9 +122,26 @@ team = gazu.project.get_team(project)
 
 ### Add a person to the project team
 
+The optional `role` argument gives the person a different role on this
+production only (see [per-project roles](/guides/permissions-roles)).
+
 ::: code-group
 ```python [Python]
 gazu.project.add_person_to_team(project, person)
+
+gazu.project.add_person_to_team(project, person, role="supervisor")
+```
+:::
+
+### Set the role of a team member
+
+Pass `None` to restore inheritance of the person's global role.
+
+::: code-group
+```python [Python]
+gazu.project.update_team_member_role(project, person, "manager")
+
+gazu.project.update_team_member_role(project, person, None)
 ```
 :::
 

docs/references/data-models.md

@@ -66,6 +66,12 @@ returns the bare revision integer. It is the minimum number of digits a
 client should use when showing a revision (`0` = no padding, `3` turns
 revision `7` into `v007`).
 
+`team` stays a plain list of person IDs. The member dicts returned by
+`GET /data/projects/<project_id>/team` additionally carry a `project_role`
+key: the role explicitly set for this production, or `None` when the
+person's global `role` applies. See the
+[per-project roles section](/guides/permissions-roles#per-project-roles).
+
 ### ProjectStatus
 
 | Field | Type | Default |
@@ -435,6 +441,7 @@ A specific instance of an asset placed in a shot or scene.
 | `display_date_format` | string (`"YYYY-MM-DD"`, `"DD/MM/YYYY"`, `"MM/DD/YYYY"`) | `"YYYY-MM-DD"` |
 | `data` | dict | |
 | `role` | string (`"user"`, `"admin"`, `"supervisor"`, `"manager"`, `"client"`, `"vendor"`) | `"user"` |
+| `project_role` | string or `None`, only in team listings | `None` |
 | `position` | string (`"supervisor"`, `"lead"`, `"artist"`) | `"artist"` |
 | `seniority` | string (`"senior"`, `"mid"`, `"junior"`) | `"mid"` |
 | `daily_salary` | int | `0` |