Flocks

#Flocks

On Emu Watch, Priya starts the Coastal Volunteers: she names it, invites Ben as a viewer and Ana as an editor, and from then on anything she shares with the flock reaches all of them — including whoever joins next month. That is a flock: a group of people inside your Nest.

Flocks are crews in the API, and your Nest is a project there: the dashboard says flock, the endpoints and the SDK say crew.

Two things are worth knowing before anything else, because they are the model in miniature:

• Being in a flock grants nothing by itself. When Ben joined the Coastal Volunteers he gained access to nothing — until Priya shared a season of sightings with it. A flock is an address you can share things to, not a power you gain by joining.
• Your tier in one flock never leaks into another. Ana is an editor in the Coastal Volunteers and could be a viewer in the Rangers; the two never mix.

On their own, flocks are a way to organise people. Combined with sharing, they become a data boundary too — share a flock's survey notes with that flock and no other flock reaches them, the way Emu Watch does it.

Everyone shares one Nest, so flocks are the tool for soft isolation within it: a flock's records for that flock, a client's records for the team serving that client, a region's data for the staff in that region.

#What you can do

• Create flocks and invite people by email — invitations carry a tier in the flock and expire after 7 days. Anyone can run one: Priya is no administrator.
• Give each member a tier: manager, editor, or viewer — Priya, Ana and Ben respectively.
• Share individual records or files with a flock, at view, edit or manage level. This is how a flock reaches a record — the only way it does.
• Control whether Nest admins can touch flocks they haven't joined, via the security.crew_isolation setting.

#Key concepts

Concept	What it means
Flock	A named group, like the Coastal Volunteers. Anyone whose role may create flocks (editors and admins by default) can make one; the creator becomes its first flock manager.
Flock tier	Your standing within a flock — manager, editor, or viewer. Separate from your Nest role: Ana's editor tier in the flock makes her an editor of nothing else.
Item share	An owner granting ONE record or file to this flock, at view / edit / manage. This is how a flock reaches a record — see flocks and sharing.
Role catalogue	The set of Nest roles a flock's managers may assign to members — how Sam lets the Rangers hand out the ranger role. Only a Nest administrator can change what is on it.
Isolation mode	The security.crew_isolation setting: how far Nest admins can reach into flocks they aren't members of.

A flock is an audience, not a data boundary. It reaches a record because somebody shared that record with it, and a member's tier caps what the share gives them. There used to be a second job — flock scoping, a crew_id on every row of a collection — and it has been removed; see flock record access.

#How it fits together

A flock never appears in a row filter. It appears in item_shares, and the permission engine adds the shared rows to what a member already reaches:

flowchart LR
    U[User] -->|belongs to| M[crew_members<br>tier: manager / editor / viewer]
    O[Record owner] -->|shares at a level| S[item_shares<br>crew_id + level]
    U -->|request| G[gateway worker]
    G -->|role grants| P[permissions]
    S --> W["rows this flock is shared"]
    M -->|tier caps the level| W
    P --> W
    W -->|composed query| D[(D1: collection records)]

Reading needs a share at any level; editing needs edit or above AND at least the editor tier; deleting needs manage AND the manager tier. Someone the flock does not reach sees an empty list rather than an error — the rows are filtered out, not forbidden.

#Guides in this section

• Managing flocks — create a flock, invite members, manage tiers, invitations and the role catalogue
• Flock record access — what replaced flock scoping, and what an operator must run before upgrading
• Flocks and sharing — how a flock reaches records, and what a share can never do
• Sharing an item — granting one record or file to a flock or a person

For the wider permission model flocks plug into — the Emu Watch example, roles, collection rules and never-rules — start with who can see what; the technical reference is access control.