# Organizations

Operational guide for an AI agent working with Briefs organizations. An org is a shared
namespace that owns Briefs on behalf of a team rather than one person. Briefs created under
an org live at `sharebriefs.com/{org}/{name}` and inherit the org's access rules.

## When to use an org

Use an org when knowledge belongs to a team or company rather than an individual: shared
design systems, internal onboarding, API docs, company knowledge bases. Personal knowledge
stays under the user's own namespace; team knowledge belongs in an org.

## Roles

- `member` — belongs to the org and can access org Briefs per the org's default permission;
  may create Briefs if the org allows it.
- `admin` — can manage org settings, invite and remove members, and manage org Briefs.

## Org settings

`update_org` (admin only) controls:

- `default_brief_permission` (`none` | `read` | `write`) — the access level org members get
  on new org Briefs by default.
- `members_can_create` (boolean) — whether non-admin members may create Briefs in the org.

Choose the least permissive defaults that still let the team work: `read` is a sensible
default for a knowledge base most members only consume.

## The tools

Lifecycle:
- `create_org` — create a new organization.
- `get_org` — fetch org details by namespace.
- `update_org` — change org settings (admin).
- `delete_org` — permanently delete an org. Destructive; admin only.
- `list_orgs` — list orgs the authenticated user belongs to.

Membership:
- `invite_to_org` — invite a user (by username) as `member` or `admin`. Creates a pending
  invitation they must accept.
- `list_org_members` — list current members and their roles.
- `remove_org_member` — remove a member (admin).
- `list_org_invitations` — list pending org invitations (admin).
- `cancel_org_invitation` — withdraw a pending org invitation (admin).
- `get_org_membership` — check the authenticated user's status in an org (active or pending).
- `accept_org_membership` / `decline_org_membership` — accept or decline an org invitation;
  `decline_org_membership` is also used to leave an org you belong to. (`leave_org` is the
  explicit leave action.)

## Invitation flow

Inviting a user creates a pending invitation. The recipient sees it via
`list_my_invitations` (type `org`) and accepts with `accept_invitation` or
`accept_org_membership`. Until accepted, they appear under `list_org_invitations`, not
`list_org_members`.

## Agent etiquette

- Confirm with the user before inviting people, changing org defaults, removing members, or
  deleting an org.
- Prefer `member` over `admin` when inviting unless admin rights are clearly intended.
- Deleting an org is destructive and affects everyone — always confirm explicitly.

## Enterprise / SSO

For company-wide setups with domain-verified single sign-on, see
https://sharebriefs.com/brief/enterprise.

## Related Briefs

- Concept overview: https://sharebriefs.com/brief/intro
- Sharing individual Briefs: https://sharebriefs.com/brief/sharing
- Lifecycle operations: https://sharebriefs.com/brief/managing