> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gainable.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Scopes
> App-wide vs personal agents, and the boundary rules between them
## Two scopes
Every Autopilot agent runs in one of two scopes. The choice is permanent for the playbook (changing it means a new playbook) and it determines who sees the work, who approves it, and what data the agent reads.
| Scope | Runs as | Sees | Drafts go to |
| ------------ | --------------- | ----------------------------------------- | -------------------------------------------------- |
| **App-wide** | The org | All app data within configured guardrails | The owner field on each record (e.g. `deal.owner`) |
| **Personal** | A specific user | Only data the user has RBAC access to | That user's Autopilot inbox |
## App-wide agents
App-wide agents act on behalf of the org. They watch all relevant data, apply objectives at scale, and route drafts to whichever user is the configured owner of each record.
### Use for
* **Stalled-deal chasers.** One playbook, scoped to all deals. Drafts route to each deal's owner.
* **SLA enforcers.** One playbook, scoped to all tickets. Escalations go to the team lead and the assigned owner.
* **Inventory watchdogs.** One playbook for the whole catalog. Reorder drafts go to the operations owner.
* **Digest publishers.** One playbook that produces an org-wide digest sent to a channel or distribution list.
### Permissions
App-wide agents read every record their guardrails allow. The runtime enforces field-level scoping (no PII unless explicitly granted), tool-level scoping (no `send_email` unless allowed), and recipient-level scoping (no external email unless the recipient class is allowed).
### Visibility
Drafts and activity from app-wide agents appear in the [Autopilot](/autopilot/inbox) of the user who owns the underlying record. A stalled-deal draft for a deal owned by Sarah appears in Sarah's inbox, not in everyone else's.
## Personal agents
Personal agents act on behalf of a single user. They run inside that user's RBAC boundary. They draft only to the user. They see only what the user is allowed to see.
### Use for
* **Daily briefings.** "My pipeline this morning." Per-user, per-timezone.
* **Personal follow-ups.** "Remind me to follow up on these three deals next week."
* **My-queue summaries.** "Top 5 things on my plate today."
* **Anything that's about *me*, not *us*.**
### Permissions
A personal agent inherits its owner's permissions. If the user can't read a record, the agent can't either. If the user has read-only access to a collection, the agent can't write to it. The user is the upper bound on the agent's authority.
### Visibility
A personal agent's drafts appear *only* in its owner's Autopilot inbox. No one else can see them, including admins (except in the [action log](/autopilot/agent-action-log) for audit purposes).
## Choosing scope
| Question | Answer |
| -------------------------------------------------------------- | ----------------------------------------- |
| Should a manager review work for their team? | **App-wide**, scope drafts to the manager |
| Should each user see their own drafts and no one else's? | **Personal** |
| Does the work cross multiple users' records? | **App-wide** |
| Is this "for me" rather than "for the team"? | **Personal** |
| Is the data sensitive enough that only the user should see it? | **Personal** |
If two answers contradict, you probably have two playbooks pretending to be one. Split them.
## Boundary rules (non-negotiable)
These rules are enforced by the runtime, not by the playbook author.
1. **A personal agent never sees data its owner can't see.** RBAC is the floor.
2. **A personal agent never drafts to anyone but its owner.** Cross-user drafting is app-wide territory.
3. **A personal agent's outputs are private by default.** Activity surfaces in the owner's Autopilot, not the org-wide feed.
4. **An app-wide agent runs as the org, not as a user.** No "I'll just elevate myself" path.
5. **An app-wide agent honors record-level ownership for routing.** A draft about Sarah's deal goes to Sarah, not the whole sales team.
6. **External recipients are bounded by allow-lists.** Both scopes. Neither can email outside the configured allowed domains without explicit graduation.
7. **The action log is the source of truth for both scopes.** Personal agents log to a private slice; app-wide agents log to the org slice. Admins can audit; users can't read each other's logs.
## Mixed-scope playbooks
You can't have one playbook that's both app-wide and personal. You can have **two playbooks** that share a template:
* An app-wide stalled-deal playbook that routes drafts to deal owners
* A personal "my stalled deals" playbook each user can opt into for richer per-user reasoning
The [autonomy contract](/autopilot/overview) often proposes both. You can keep one, both, or neither.
## Examples
### App-wide example
```yaml theme={null}
name: SLA enforcer
scope: app_wide
trigger:
type: schedule
cron: "*/15 * * * *"
steps:
- tool: query_collection
collection: tickets
filter: "status = 'open' AND age_hours > 24"
- tool: draft_for_approval
template: sla_breach
owner: "{{ ticket.assignee }}"
guardrails:
rate_limit_per_user: "5/day"
```
### Personal example
```yaml theme={null}
name: Daily briefing
scope: personal
trigger:
type: schedule
cron: "0 8 * * 1-5"
timezone: "{{ user.timezone }}"
steps:
- tool: query_collection
collection: deals
filter: "owner = {{ user.id }}"
sort: "amount desc"
limit: 5
- tool: draft_for_approval
template: daily_briefing
owner: "{{ user.id }}"
guardrails:
rate_limit_per_user: "1/day"
```
## Best practices
If the playbook reasons about more than one user's records, app-wide is almost always the right scope.
Daily briefings, my-queue summaries, and on-demand drafts belong in personal scope.
Personal and app-wide agents have separate slices of the action log on purpose. Cross-scope reasoning is a sign you actually have two objectives.
[Simulate on last 30 days](/autopilot/playbooks) shows you exactly which records and which users would have been touched. Use it to verify the boundary is where you think it is.
## Learn more
What Autopilot agents are
Where scope is configured
Where drafts surface, scoped accordingly
The audit trail, sliced by scope