> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> How Aion uses visibility boundaries for behaviors, tools, and request context.

A scope is a visibility boundary.

Aion uses scopes to answer questions like:

* where a behavior can be included
* which capabilities a daemon can discover
* which tools make sense for the current request
* how far a runtime identity may look beyond its own node

Not every Aion feature supports every scope. A behavior sharing scope, an MCP
tool search scope, and an authorization reach may use overlapping vocabulary
while enforcing different rules. The common idea is that a scope narrows the
set of things that should be visible for a particular operation.

## Scope Types

* `Public`: visible from public entrypoints or everywhere a public surface is
  exposed. This is used for public agent cards, public distribution surfaces,
  and unauthenticated discovery where supported.
* `Aion`: visible across the Aion platform. This is used for platform-provided
  system behaviors, control-plane capabilities, and globally available
  defaults.
* `Organization`: visible within the same organization. This is used for
  organization-shared behaviors and organization-wide capability discovery.
* `Project`: visible within the same project. This is used for project-local
  behavior inclusion, project-scoped capability discovery, and project-level
  daemon tool access.
* `Request`: visible within the current distribution request path up to the
  caller. This is used for contextual tool discovery inside an agent sequence.
* `Node`: visible to one configured agent environment. This is used for
  self-node capability discovery and isolated daemon access.

## Project Scope

Project scope is the normal boundary for work that belongs to one composed
agent system.

A project contains nodes. Each node is backed by an agent environment, and each
environment resolves the behavior, configuration, identities, and enabled
capabilities for that node. Project scope lets a daemon discover tools or
behaviors that belong to the same composed system without automatically
crossing into unrelated projects.

```mermaid actions={false} theme={null}
flowchart LR
  subgraph Project["Project"]
    Distribution["Distribution"]
    Middleware["Middleware node"]
    Terminal["Terminal node"]
    Tool["MCP-capable node"]
  end

  Distribution --> Middleware --> Terminal
  Middleware -. project scope .-> Tool
```

Project scope is broader than node scope. A node-scoped request can see only
one configured environment. A project-scoped request may see other resources in
the same project when the caller has project-level capability discovery access.

## Request Scope

Request scope is narrower than project scope.

When a request enters through a distribution, Aion resolves an agent sequence:
an ordered list of agent environments that may participate in that request.
If a middleware node asks for request-scoped tools, Aion exposes only the
sequence prefix from the distribution ingress through that caller.

```mermaid actions={false} theme={null}
flowchart LR
  Distribution["Distribution ingress"]
  MiddlewareA["Middleware A"]
  MiddlewareB["Middleware B"]
  Terminal["Terminal agent"]

  Distribution --> MiddlewareA --> MiddlewareB --> Terminal

  classDef visible fill:#eaf7ff,stroke:#1477a8,color:#0b3044
  class Distribution,MiddlewareA visible
```

In this example, if `Middleware A` searches with request scope, the visible
request scope is:

* the distribution ingress
* `Middleware A`

It does not include `Middleware B` or the terminal agent. This avoids leaking
downstream sequence details to an upstream caller and keeps tool discovery
aligned with the context that has actually led to the caller.

Request scope requires a distribution id as the contextual id. Aion then
resolves the caller's runtime principal to an agent environment and truncates
the distribution sequence at that environment.

## Node Scope

Node scope is the smallest agent-runtime scope.

It is anchored to one agent environment. Use node scope when an agent needs to
answer "what can I do?" or when an isolated daemon should discover only tools
attached to its own configured environment.

Node scope is intentionally not a fallback for request scope. If an operation
requires request or project visibility and the caller lacks that access, Aion
rejects the request instead of returning a partial view that could imply the
larger sequence is smaller than it really is.

## Where Scopes Appear

Scopes appear in several places:

* Behavior sharing uses scopes such as `Project`, `Organization`, and `Aion`
  to decide where behavior deployments can be included.
* MCP tool discovery uses scopes such as `node`, `request`, `project`, and
  `organization` to decide which tools are visible to a daemon.
* Authorization roles may use contextual reach such as node, project, or
  organization reach to decide whether a principal can list or execute a
  capability.

The available scopes depend on the operation. A caller should use the narrowest
scope that still matches the user's request and the runtime context.

See [Behaviors](/docs/concepts/behaviors),
[Agent Environments](/docs/concepts/environments),
[Nodes](/docs/concepts/nodes), and
[MCP Resources](/docs/concepts/mcp-resources) for the related models.