# Sharing Briefs and Managing Access

Operational guide for an AI agent sharing individual Briefs and managing who can read or
edit them. This covers per-Brief collaborators and permissions. For team-wide access
through an organization, see https://sharebriefs.com/brief/organizations.

## Two ways to give access

1. **The link.** A public Brief needs no authentication — anyone with the URL can read it.
   For most sharing, handing over the URL is all that is required. Do not add collaborators
   just to let someone read a public Brief. (Private and internal Briefs are not
   link-readable; see below for private Briefs and the organizations Brief for internal ones.)
2. **Collaborators.** For private Briefs, or to grant editing rights, add named users as
   collaborators with a specific permission level.

## Permission levels

- `read` — can fetch and read the Brief (relevant for private Briefs).
- `write` — can read and edit the Brief's content.
- `admin` — can read, edit, change visibility, manage collaborators, rename, and delete the
  Brief.

## The tools

- `add_collaborator` — add a user (by username) at a permission level, or update an existing
  collaborator's level. If the user is not yet a collaborator, this creates an invitation
  they must accept.
- `list_collaborators` — see who currently has access to a Brief and at what level.
- `remove_collaborator` — revoke a user's access. Requires admin access.
- `check_permission` — check what permission a specific user has on a Brief. Use this before
  assuming someone can read or edit.
- `list_brief_invitations` — see pending (not-yet-accepted) invitations for a Brief.
- `update_brief_invitation` — change the permission level on a pending invitation.
- `cancel_brief_invitation` — withdraw a pending invitation before it is accepted.

## Invitations vs active collaborators

Adding a collaborator who is not already on the Brief creates a pending invitation. The user
appears as a collaborator only once they accept. So after `add_collaborator`, expect the
target to show up under `list_brief_invitations` until accepted, then under
`list_collaborators`. The recipient accepts via `accept_invitation` (see the invitations
flow in the organizations Brief and intro).

## Agent etiquette

- Grant the least privilege that accomplishes the goal: `read` unless editing is intended.
- Confirm with the user before adding `admin` collaborators or removing anyone's access.
- For simple "let them see it" requests on a public Brief, just share the URL — don't invite.
- Use usernames exactly; look them up with `get_user` if unsure.

## Related Briefs

- Concept overview: https://sharebriefs.com/brief/intro
- Lifecycle operations (update/delete/list): https://sharebriefs.com/brief/managing
- Team/org access: https://sharebriefs.com/brief/organizations