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

# Agent Pools

> Named groups of profiles that share a filesystem workspace and a lightweight blackboard.

## What is a Pool?

An **Agent Pool** groups profiles that need to collaborate through shared state. Pools add two things to each member profile:

* A role-aware filesystem policy under `/pools/{pool}/...`
* Pool tools: `pool_info`, `pool_post`, and `pool_inbox`

Pool membership does not replace the profile sandbox. Every profile still keeps its implicit home at `/agents/{self}/**`; pool access is layered on top.

***

## Pool Schema

```go theme={null}
type AgentPool struct {
  ID          string
  Name        string
  Description string
  Members     []PoolMember
  FS          *PoolFSPolicy
}

type PoolMember struct {
  Profile string
  Role    string // "lead" | "member" | "observer"
}
```

Roles default to `member` when omitted or unknown.

***

## Creating a Pool

```bash theme={null}
curl -X POST https://api.orcapods.ai/api/pools \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "research-team",
    "description": "Shared workspace for market research",
    "members": [
      { "profile": "researcher", "role": "lead" },
      { "profile": "reviewer", "role": "member" },
      { "profile": "auditor", "role": "observer" }
    ],
    "fs": {
      "read": ["/datasets/**"],
      "write": ["/pools/{pool}/sot/**"],
      "deny": ["/pools/{pool}/archive/private/**"]
    }
  }'
```

The conductor broadcasts pools to all runners, just like profiles.

***

## Built-in Path Layout

Every pool uses the same directory conventions:

| Path                                  | Purpose                               |
| ------------------------------------- | ------------------------------------- |
| `/pools/{pool}/sot/`                  | Shared source-of-truth documents      |
| `/pools/{pool}/board/public/`         | Public blackboard for all members     |
| `/pools/{pool}/board/public/posts/`   | Markdown posts created by `pool_post` |
| `/pools/{pool}/board/private/{self}/` | Member-private workspace              |
| `/pools/{pool}/archive/`              | Shared archive                        |

`pool_info` returns the concrete paths for the active session.

***

## Role Permissions

| Role       | Read                                             | Write                                            | Delete                |
| ---------- | ------------------------------------------------ | ------------------------------------------------ | --------------------- |
| `lead`     | `sot`, public board, all private boards, archive | `sot`, public board, all private boards, archive | `sot`, board, archive |
| `member`   | `sot`, public board, own private board, archive  | public board, own private board                  | own private board     |
| `observer` | `sot`, public board, archive                     | none                                             | none                  |

Custom `fs.read`, `fs.write`, `fs.delete`, and `fs.deny` entries are additive. `deny` always wins.

***

## Pool Tools

`@pool` is part of `@default`, so normal profiles can inspect pool membership immediately. Tools that read or write posts use the runner's VirtualFS dispatcher; with no `VFS_*` environment they still work in that runner's in-memory storage, but posts are not shared with `vfs serve` or other runner processes.

| Tool         | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `pool_info`  | Returns pool memberships, role, roster, and path layout         |
| `pool_post`  | Writes a markdown post to `/pools/{pool}/board/public/posts/`   |
| `pool_inbox` | Lists recent public posts; use `read_file` to fetch a full post |

Typical agent workflow:

1. Call `pool_info` to discover memberships and paths.
2. Call `pool_inbox` to catch up on recent public posts.
3. Use `read_file` / `write_file` for shared documents.
4. Call `pool_post` for updates other members should see.

***

## Effective Filesystem Policy

The runner compiles a session policy in this order:

1. Implicit home grant: `/agents/{self}/**`
2. Profile `fs` grants and denies
3. Built-in pool grants for each membership role
4. Pool custom `fs` grants and denies

Tokens are substituted before matching:

| Token    | Value                |
| -------- | -------------------- |
| `{self}` | Current profile name |
| `{pool}` | Pool name            |
| `{role}` | Member role          |

Relative paths in `read_file`, `write_file`, and `delete_file` resolve under `/agents/{self}/`. Use absolute paths for pool files.