# Who sees which bugs

BugTape's visibility model is deliberately simple. Read this before asking for per-user permissions.

## The model

```
Organization  (membership + role: admin · manager · member · tester · viewer)
  └─ Project  (an app, a service, a client — one API key each)
       └─ Issue (grouped failures)
            └─ Occurrence (platform · release · environment · end user)
```

- **Membership is per organization.** Every member of an org can *read* every project in it. Roles gate *writes* (rename/delete projects, invite, billing, minting agent tokens), not reads.
- **Projects are the sharing unit.** A dev shop running five client apps puts each client in its own **organization** (the workspace switcher hops between them, and the Portfolio page rolls them up). Projects inside one org are for *your own* apps and services — web, iOS, backend — that the same people should see.
- **Agents are members too.** An agent PAT belongs to an org and reads what that org's humans read, narrowed by scopes (`subscribe`, `get_repro_context`, `suggest_fix`, `create_bug`). Human-only actions (watch, destructive project ops, minting tokens) refuse PATs.

## Narrowing what *you* look at

None of these change permissions; they are views, and they live in the URL so they can be shared:

| Need | Where |
|---|---|
| One app or service | Workspace switcher → project, or `?projectId=` on Issues |
| One surface | **Platform** facet on Issues (`?platform=ios`) — the same issue can span web + iOS |
| My work | **Mine** / **Unassigned** on Issues (`?assignee=me` / `unassigned`) |
| The agent's queue | **Recommended** tab (`GET /v1/bugs/recommended`) |
| Noise you never want to see | Alerts → Ignore rules (project-scoped, expiring, matcher-based) |
| One customer's experience | Affected users on a bug → **Timeline** (`/users/<userKey>`) |

Agents get the same knobs: `list_bug_groups({ projectId, platform })`, `list_recommended_critical`, `get_user_timeline`.

## What is *not* here (yet)

- **Per-project roles / project allow-lists.** A `viewer` sees every project in the org. This is ROADMAP M4 ("Granular RBAC") and will attach at one choke point (`resolveOrgAccess` → an allowed-project set) rather than per route. If you need a wall between two audiences today, use two organizations.
- **Saved views.** Filters are URL state; bookmark the URL.

## Why it is shaped this way

Solo teams and small shops asked for "one pane across every client" far more often than "hide project B from Sara". Organizations give the wall; projects give the pane. Adding per-project permissions before there is a paying team that needs them would slow every query for everyone.