---
title: "Referência do manifesto"
description: "Todas as chaves do beeuni.yaml v2, com valores padrão, limites e regras de validação."
---

O manifesto é o arquivo que a plataforma considera a fonte oficial de um projeto. Esta página lista todas as chaves `beeuni.yaml` (v2), seus tipos, valores padrão e como a plataforma as valida. Para uma versão em linguagem simples, consulte [Seu projeto](/docs/pt/project).

<a id="two-configuration-surfaces"></a>

## Duas superfícies de configuração

Um projeto Beeuni tem duas superfícies de configuração com responsabilidades estritas e sem sobreposição.

- **Configuração Beeuni** — `beeuni.yaml` na raiz do repositório define o ambiente do projeto, os agentes, as ferramentas, os conectores e os gatilhos. Os modelos de sandbox podem referenciar um Dockerfile personalizado.
- **Configuração do agente** — os arquivos do agente, as skills e os arquivos do harness. O harness do agente lê isso, no sandbox e localmente.

| Caminho | O que contém |
| --- | --- |
| `beeuni.yaml` | O manifesto: agentes e o que cada um pode acessar, gatilhos, conectores, env e modelos de sandbox. |
| `agents/<name>.md` | Um agente: frontmatter e prompt do sistema. `agents.<name>.file` o identifica. |
| `skills/<name>/SKILL.md` | Uma skill. Todos os harnesses a carregam. |
| `memory/` | A memória do projeto. |
| `tools/<name>.ts` | Ferramentas do projeto, uma por módulo. `tools:` as declara; todos os harnesses as executam. Consulte [Ferramentas](/docs/pt/project/tools). |
| `harnesses/opencode/` | Arquivos lidos apenas pelo harness padrão: `opencode.jsonc`, `plugins/`, `tools/`, `commands/`. `opencode.config_dir` aponta para aqui. |

Projetos criados antes de 2026-09 mantêm os agentes e as skills em `.beeuni/opencode/` e a memória em `.beeuni/memory/`. O Beeuni lê os dois formatos.

A conexão entre as duas partes é o arquivo `.md` do agente. Uma chave do manifesto `agents.<name>` controla o arquivo indicado por `agents.<name>.file` ou `agents/<name>.md` quando `file` é omitido. Todos os campos comportamentais ficam apenas no frontmatter e no corpo desse arquivo `.md`, nunca em `beeuni.yaml`:

- prompt do sistema
- `model`, `mode`
- `temperature`, `top_p`
- `steps`, `permission`

O bloco `agents:` do manifesto define apenas a governança: quais agentes podem ser iniciados e o que cada um pode acessar. O validador aplica essas regras. Ele rejeita um bloco de agente v2 que contenha qualquer campo comportamental, com um erro que aponta para o próprio arquivo `.md` do agente.

<a id="location-and-versions"></a>

## Localização e versões

Qualquer repositório com um manifesto válido na raiz é um projeto Beeuni. `beeuni.yaml` (v2, somente YAML) é o formato atual para novos projetos, criados pelo fluxo web "Create project" e por `beeuni init`. `beeuni.toml` (v1) ainda funciona para projetos existentes, mas a plataforma não aceita novos recursos v2 nesse formato. Consulte [TOML legado](/docs/pt/project/legacy-toml) para ver o esquema v1 e as etapas de migração de v1 para v2.

`beeuni_version: 2` exige YAML — um arquivo `.toml` que declare `beeuni_version: 2` não passa na validação. Um manifesto que declare uma versão superior a `2` é rejeitado diretamente, para que a plataforma nunca interprete incorretamente um campo futuro sem avisar. Chaves desconhecidas no nível superior são ignoradas, então você pode guardar seus próprios metadados no arquivo.

`validateManifest()` é a única etapa de validação usada por `beeuni ship`, pela verificação de mesclagem de solicitações de alteração e por `beeuni validate`. As mesmas regras se aplicam em todos os lugares, então tudo o que é mesclado em `main` tem uma estrutura válida. O esquema é público e gerado a partir do mesmo pacote:

- [`beeuni.v2.schema.json`](/schema/beeuni.v2.schema.json)
- [`beeuni.v1.schema.json`](/schema/beeuni.v1.schema.json)
- [`beeuni.schema.json`](/schema/beeuni.schema.json) (seleciona o formato com base em `beeuni_version`)

Aponte um `beeuni.yaml` para o esquema v2 para validar no editor ou obtenha-o pela CLI:

```yaml
# yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json
beeuni_version: 2
```

```bash
beeuni schema --version 2
```

<a id="full-example"></a>

## Exemplo completo

```yaml
beeuni_version: 2
default_agent: beeuni

project:
  name: my-project
  description: What this project is.

env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET]

sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16

opencode:
  config_dir: harnesses/opencode

agents:
  beeuni:
    file: agents/beeuni.md
    connectors: all
    secrets: all
    beeuni_permissions: all
    skills: all

  release-bot:
    file: agents/release-bot.md
    sandbox: ml
    connectors: [github]
    beeuni_permissions: [project.gitops.push]
    secrets: [GITHUB_AGENT_TOKEN]

triggers:
  - slug: daily-digest
    type: cron
    agent: beeuni
    cron: '0 0 9 * * 1-5'
    timezone: America/Los_Angeles
    prompt: |
      Summarize yesterday's commits. Open a CR against main.
```

<a id="top-level-keys"></a>

## Chaves de nível superior

| Chave                                                 | Obrigatória | Observações                                                                                      |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `beeuni_version`                                    | sim      | deve ser `2`                                                                                |
| `default_agent`                                     | sim      | deve indicar um agente declarado e habilitado                                                        |
| `imports`                                           | não       | outros arquivos ou diretórios YAML cujos `triggers`, `connectors`, `agents`, `apps` e `tools` são mesclados a este manifesto. Consulte [`imports:`](#imports) |
| `tools`                                             | não       | as ferramentas disponíveis em todas as sessões: nome da ferramenta → caminho do módulo relativo ao repositório, ou `beeuni:<name>` para uma ferramenta Beeuni. Com uma chave `tools`, as sessões recebem apenas as ferramentas Beeuni listadas nela. Todos os harnesses as executam. Consulte [`tools:`](#tools) |
| `runtime`                                           | não       | `"opencode"` (padrão) ou `"pi"` — o harness do agente que uma sessão inicia dentro do sandbox; `pi` executa o harness experimental no processo, no daemon do sandbox, e lê os mesmos arquivos `.md` do agente e as mesmas skills. O sinalizador de recurso `pi_harness` do projeto seleciona harness experimental sem esta linha. O harness experimental precisa do sinalizador `llm_gateway`; sem ele, a sessão inicia o harness padrão. |
| `harnesses.pi.packages`                             | não       | pacotes harness experimental carregados pelas sessões harness experimental do projeto. Consulte [`harnesses:`](#harnesses) |
| `pi.config_dir`                                    | não       | `harnesses/pi` e, depois, `.beeuni/pi`, se presente. Recursos nativos do harness experimental: `settings.json`, `extensions/`, `skills/` e `prompts/`. |
| `project.name` / `project.description`              | não       | metadados de exibição; a plataforma não lê `project.name` para obter o nome de exibição do projeto |
| `env.required` / `env.optional`                     | não       | nomes de variáveis de ambiente; `required` é apenas informativo e nunca é aplicado no início da sessão                |
| `sandbox` / `sandbox.templates` / `sandbox.default` | não       | imagem(ns) e hardware do sandbox                                                              |
| `opencode.config_dir`                               | não       | `harnesses/opencode` padrão, seguido de `.beeuni/opencode` legado                           |
| `triggers`                                          | não       | lista de gatilhos cron, webhook e monitor                                                |
| `connectors`                                        | não       | lista de definições de conectores                                                              |
| `policy.default_mode`                               | não       | `allow_all` (padrão) ou `risk`; modo de aprovação de conectores para todo o projeto                      |
| `agents`                                            | sim      | mapa de governança de nomes para blocos; não pode estar vazio. Com `imports`, o mapa pode estar em um arquivo importado |

## `imports:`

Divida um manifesto em vários arquivos YAML. Use essa opção quando `beeuni.yaml` ultrapassar uma tela: 30 gatilhos com prompts de várias linhas, um conector por equipe, um arquivo por grupo de agentes.

```yaml
# beeuni.yaml
beeuni_version: 2
default_agent: beeuni
imports:
  - triggers/                # a directory: every .yaml and .yml file below it
  - agents.yaml              # a single file
agents:
  beeuni:
    connectors: all
```

```text
beeuni.yaml
agents.yaml
triggers/
  reports/
    weekly.yaml
    monthly.yaml
  dockets/
    freedom-forever.yaml
```

```yaml
# triggers/reports/weekly.yaml
triggers:
  - slug: weekly-report
    name: Cross-Sector Weekly Report
    type: cron
    agent: galileo
    cron: "0 15 * * 0"
    prompt: |-
      Build the weekly report.
```

O arquivo raiz e suas importações formam uma configuração de projeto. Um gatilho em um arquivo pode indicar um agente declarado em outro.

**Regras**

1. Um caminho é relativo à raiz do repositório. `..`, caminhos absolutos e globs são rejeitados.
2. Uma importação de diretório inclui todos os arquivos `.yaml` e `.yml` abaixo dele, em qualquer profundidade, ordenados pelo caminho. Os outros arquivos são ignorados.
3. Um arquivo importado declara `triggers`, `connectors`, `agents`, `apps`, `tools` e `imports`. Todas as outras chaves (`beeuni_version`, `default_agent`, `runtime`, `project`, `env`, `opencode`, `sandbox`, `policy`, `policies`) permanecem no arquivo raiz. Se um arquivo importado definir uma delas, a validação falhará.
4. Um arquivo importado pode importar outros arquivos. O limite é de 8 níveis e 200 arquivos. Um ciclo é um erro. Um arquivo encontrado mais de uma vez é mesclado apenas uma vez.
5. Um nome, um arquivo. Se um slug de acionador, slug de conector, nome de agente, nome de app ou nome de ferramenta for declarado em dois arquivos, ocorrerá um erro que identifica ambos. Nada é sobrescrito silenciosamente.
6. As entradas são mescladas na ordem: primeiro o arquivo que importa e, em seguida, as importações na ordem listada.

Uma importação inválida faz todo o manifesto falhar, assim como um erro de sintaxe YAML. `beeuni validate`, `beeuni ship` e a verificação de mesclagem da solicitação de alteração também informam o erro antes que ele chegue a `main`:

```text
imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file
```

**As edições são feitas no arquivo que declara a entrada.** Quando o dashboard, a API ou `beeuni triggers enable|disable|rm` altera um acionador, conector, agente ou app declarado em um arquivo importado, somente esse arquivo é gravado. O arquivo raiz não é regravado. Uma nova entrada é gravada no arquivo raiz. Mova-a manualmente para um arquivo importado se quiser que ela fique lá.

`imports` exige `beeuni.yaml`. Um manifesto `beeuni.toml` ignora a chave.

## `tools:`

As ferramentas que uma sessão recebe, identificadas pelo nome. Há dois formatos possíveis para um valor:

| Formato | Significado |
| --- | --- |
| `beeuni:<name>` | Uma ferramenta Beeuni (`web_search`, `image_search`, `scrape_webpage`, `memory`, `show`), mantida pela Beeuni. A chave deve ser `<name>`. |
| Um caminho de módulo relativo ao repositório | Uma ferramenta do próprio projeto, em qualquer pasta. Se estiver sob o nome de uma ferramenta Beeuni, o módulo substitui a ferramenta Beeuni. |

```yaml
tools:
  web_search: beeuni:web_search
  image_search: beeuni:image_search
  scrape_webpage: beeuni:scrape_webpage
  memory: tools/memory.ts                # replaces the Beeuni memory tool
  lookup_order: tools/lookup_order.ts
  crm_note: integrations/crm/note.ts
```

harness padrão e harness experimental executam o mesmo módulo. O contrato do módulo, `beeuni tools ls`,
`beeuni tools eject` e a migração de `harnesses/opencode/tools/` estão em
[Tools](/docs/pt/project/tools).

**Regra de seleção.**

- Sem a chave `tools` no arquivo raiz nem em qualquer arquivo importado: as sessões recebem todas as cinco ferramentas Beeuni. Todo projeto criado antes de a lista existir continua com elas.
- Com a chave `tools`, mesmo vazia (`tools: {}` ou `tools:` com todas as linhas excluídas): as sessões recebem apenas as ferramentas Beeuni listadas, como `beeuni:<name>` ou como caminho de módulo. Uma chave `tools` em um arquivo importado também conta.

Exclua uma linha `beeuni:<name>` para remover essa ferramenta de todos os agentes. Use
[`agents.<name>.tools`](/docs/pt/project/tools#who-may-use-which-tool) para limitar uma
única agente.

**Erros.**

- O nome deve estar em snake_case: `^[a-z][a-z0-9_]{0,63}$`.
- Um nome de ferramenta do harness (`bash`, `read`, `write`, `edit`, `apply_patch`, `glob`, `grep`, `list`, `task`, `question`, `todowrite`, `webfetch`, `websearch`, `skill`, `lsp`, `invalid`, `execute`, `plan_exit`, `pty_*`) é um erro.
- O caminho termina em `.ts`, `.js`, `.mts`, `.mjs`, `.cts` ou `.cjs`. Não pode começar com `/` ou `-`, nem conter um segmento `.` ou `..`.
- `beeuni:<name>` em outra chave é um erro. Sob o nome de uma ferramenta Beeuni, por exemplo, `web_search: beeuni:image_search`:

  ```text
  tools.web_search: deve ser `beeuni:web_search` (a ferramenta Beeuni) ou um caminho relativo ao repositório para um módulo .ts ou .js (por exemplo, `tools/web_search.ts`) que a substitua.
  ```

- `beeuni:<name>` para um nome que não seja de uma ferramenta Beeuni, por exemplo, `web_serch: beeuni:web_serch`:

  ```text
  tools.web_serch: deve ser um caminho relativo ao repositório para um módulo .ts ou .js (por exemplo, `tools/web_serch.ts`). `beeuni:<name>` nomes uma ferramenta Beeuni pelo próprio nome: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`.
  ```

- `beeuni validate` também informa sobre um módulo declarado que não existe. Um valor `beeuni:` não precisa de arquivo.

**Avisos.** Um aviso nunca faz `beeuni validate` falhar.

- Uma chave `tools` que não lista nenhuma das cinco ferramentas Beeuni:

  ```text
  tools: as sessões deste projeto não recebem nenhuma ferramenta Beeuni (web_search, image_search, scrape_webpage, memory, show). Adicione `<name>: beeuni:<name>` para manter uma.
  ```

  Isso detecta se um projeto adiciona sua primeira ferramenta própria e remove as cinco por acidente.
- O `tools` de um agente que menciona uma ferramenta Beeuni que o projeto não carrega:

  ```text
  agents.beeuni.tools: "show" é uma ferramenta Beeuni que este projeto não carrega: adicione `show: beeuni:show` em `tools` no nível superior ou remova-a daqui.
  ```

## `project:`

Metadados opcionais, voltados a pessoas: `name` e `description`. A plataforma não lê esta tabela para nenhuma finalidade — o nome de exibição de um projeto vem do próprio registro no banco de dados. Considere-a documentação para quem lê o repositório.

## `env:`

Declara os nomes das variáveis de ambiente necessárias às sessões. Os valores ficam na página Environment variables do dashboard, nunca diretamente no manifesto. A plataforma os descriptografa e os injeta como variáveis de ambiente comuns no início da sessão.

```yaml
env:
  required: [DATABASE_URL]
  optional: [STRIPE_API_KEY]
```

| Campo | Tipo | Observações |
| ---------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `required` | `string[]` | Informativo. O dashboard solicita esses valores ao usuário, mas o início da sessão não é bloqueado se um valor estiver ausente. |
| `optional` | `string[]` | Disponível para as sessões se definido. Pode estar ausente. |

Os nomes das variáveis de ambiente correspondem a `^[A-Z_][A-Z0-9_]*$`. O Secrets Manager limita os nomes a 64 caracteres — um nome mais longo é aceito aqui, mas nunca poderá receber um valor. Nomes que começam com `BEEUNI_` também nunca poderão receber um valor. Limite os nomes a 64 caracteres e evite o prefixo `BEEUNI_`. Contrato completo: [Secrets](/docs/pt/project/secrets).

<a id="sandbox-and-sandboxtemplates"></a>

## `sandbox:` e `sandbox.templates`

Uma lista de imagens de sandbox nomeadas que podem ser iniciadas. Opcional — sem entradas, todas as sessões iniciam com a imagem padrão da plataforma. Cada modelo precisa ter exatamente um de `dockerfile` (relativo ao repositório) ou `image` (uma referência pública do Docker, com tag ou digest fixado).

```yaml
sandbox:
  templates:
    - slug: ml
      name: ML Development
      dockerfile: Dockerfile.ml
      cpu: 4
      memory: 16
      disk: 50
```

| Campo        | Tipo   | Padrão             | Observações                                                                       |
| ------------ | ------ | ------------------- | --------------------------------------------------------------------------------- |
| `slug`       | string | —                   | Obrigatório. Exclusivo por projeto. `default` é reservado.                         |
| `name`       | string | slug                | Rótulo exibido no seletor do painel.                                              |
| `dockerfile` | string | —                   | Caminho relativo ao repositório. Mutuamente exclusivo com `image`.              |
| `image`      | string | —                   | Imagem Docker pública, fixada por tag ou digest. Mutuamente exclusiva com `dockerfile`. |
| `entrypoint` | string | própria da camada de runtime | Substitui o entrypoint do contêiner.                                               |
| `cpu`        | int    | padrão do provedor  | Núcleos de vCPU. Limite: 1–32.                                                    |
| `memory`     | int    | padrão do provedor  | RAM em GiB. Limite: 1–128.                                                        |
| `disk`       | int    | padrão do provedor  | Disco em GiB. Limite: 1–500.                                                      |
| `container_runtime` | bool | `false`       | Executa o Docker na sandbox com rede bridge + overlay. Consulte [Runtime](/docs/pt/work/runtime#docker-in-the-sandbox). |

Cada valor deve ser um inteiro positivo. Um valor abaixo do mínimo falha na validação com um erro. Um valor acima do máximo passa com um aviso e, em seguida, é limitado em tempo de execução. GPUs não são compatíveis — declarar `gpu` gera um aviso, não um erro. Consulte [Runtime](/docs/pt/work/runtime) para saber o que a camada de runtime injeta sobre a sua imagem.

### `sandbox.default`

Defina `default` em `sandbox` para tornar um template o padrão de todo o projeto. Todas as sessões, triggers e canais passam a inicializá-lo sem especificar um slug.

```yaml
sandbox:
  default: dev
  templates:
    - slug: dev
      dockerfile: Dockerfile.dev
```

`default` deve indicar um template declarado neste manifesto ou o valor reservado `"default"` para a imagem da plataforma.

Um agente pode selecionar seu ambiente com `agents.<name>.sandbox`. O valor deve indicar um template do manifesto ou do painel, ou `"default"`.

```yaml
agents:
  researcher:
    sandbox: ml
```

A resolução do template da sessão segue esta ordem:

1. `sandbox_slug` explícito da sessão.
2. `sandbox` do agente selecionado.
3. `sandbox.default` do projeto.
4. `"default"` da plataforma.

Triggers de cron, triggers de webhook, agendamentos e canais usam o template do agente selecionado.

Uma alteração na especificação (`cpu`, `memory`, `disk`, `container_runtime` ou na própria imagem) recria o snapshot do projeto. O novo tamanho se aplica à próxima sessão, não a uma sessão em andamento.

## `opencode:`

Onde fica o diretório de configuração do harness padrão. Opcional, com um valor padrão.

```yaml
opencode:
  config_dir: harnesses/opencode
```

| Campo        | Tipo   | Padrão                                          | Observações              |
| ------------ | ------ | ----------------------------------------------- | ------------------------ |
| `config_dir` | string | `harnesses/opencode`, depois `.beeuni/opencode`   | Diretório relativo ao repositório. |

Quando `config_dir` não está definido, o Beeuni usa o primeiro entre `harnesses/opencode` e `.beeuni/opencode` que contenha um `opencode.json` ou `opencode.jsonc`. Esse diretório contém apenas os arquivos lidos pelo harness padrão: `opencode.jsonc`, `plugins/`, `tools/` e `commands/`. Os agentes e as skills ficam na raiz do repositório, em `agents/` e `skills/`. `opencode.jsonc` continua sendo o registro nativo do harness padrão para plugins, servidores MCP, provedores e permissões — não duplique essas configurações no manifesto. Consulte [Agents](/docs/pt/project/agents).

## `harnesses:`

Configurações específicas de cada harness. `pi.config_dir` aponta para um diretório relativo ao repositório com configurações nativas do harness experimental (padrão: `harnesses/pi`, depois `.beeuni/pi`). O diretório é importado durante a inicialização do harness experimental. `pi.packages` é separado: ele instala pacotes por agente a partir de `harnesses.pi.packages` do manifesto. Atualmente, existe uma chave de pacote: `pi.packages`, os pacotes do harness experimental carregados por todas as sessões do harness experimental deste projeto (`runtime: pi` ou a flag `pi_harness`). Um pacote pode ser qualquer coisa de packages: extensões (ferramentas, hooks, comandos), além das skills e dos prompts incluídos no pacote.

```yaml
runtime: pi
harnesses:
  pi:
    packages:
      - npm:pi-web-access@0.30.0            # pinned extension version
      - source: npm:pi-mcp-adapter@2.36.0
        extensions: ["extensions/*.ts"]     # load only these files of the package
        skills: []                          # load none of its skills
      - ./harnesses/pi/audit.ts             # an extension file in this repository
```

| Formato da entrada | Significado |
| --- | --- |
| `npm:<name>@<x.y.z>` | Um pacote npm em uma versão exata. Um intervalo de versões ou a ausência de versão causa falha na validação. |
| `./<path>` | Um arquivo de extensão ou diretório de pacote neste repositório. Não pode sair do repositório usando `..`. |
| `{ source, extensions, skills, prompts, themes }` | A mesma origem com os filtros de inclusão/exclusão próprios do harness experimental. Se nenhum filtro for especificado, tudo é carregado; `[]` não carrega nada. |

No máximo 20 entradas. Fontes Git são rejeitadas.

<a id="per-agent"></a>

### Por agente

Um agente pode adicionar seus próprios pacotes e remover pacotes de nível superior, em `agents.<name>.harnesses`:

```yaml
harnesses:
  pi:
    packages: [npm:pi-web-access@0.30.0]            # every agent
agents:
  researcher:
    harnesses:
      pi:
        packages: [npm:@juicesharp/rpiv-todo@2.11.0] # researcher only
  reviewer:
    harnesses:
      pi:
        exclude: [pi-web-access]                     # reviewer loads no web tools
```

- Os pacotes de um agente são a lista de nível superior, menos os itens em `exclude`, mais os itens em `packages`.
- Se uma entrada de um agente corresponder a um pacote também listado no nível superior, ela substitui a entrada de nível superior para esse agente (outra versão ou outros filtros).
- `exclude` lista nomes de pacotes (`pi-web-access`, `@scope/name`) ou caminhos `./` tal como escritos na lista de nível superior. Nunca recebe uma versão.
- Cada lista de pacotes distinta é compilada uma vez. Agentes com a mesma lista compartilham a compilação.
- Os pacotes pertencem ao agente com o qual uma sessão é iniciada. Um subagente iniciado por outro agente com a ferramenta `task` usa apenas as ferramentas de espaço de trabalho padrão (`bash`, `read`, `write`, `edit`, `glob`, `grep`), e não os próprios pacotes nem os do agente principal; os hooks de extensão do agente principal ainda se aplicam às chamadas dele. Inicie uma sessão com esse agente para usar os pacotes dele.

Como os pacotes chegam a uma sessão:

1. Ao mesclar a solicitação de alteração que edita esta lista, os pacotes são compilados uma vez para a plataforma de sandbox, com os scripts de instalação desativados. Cada extensão é pré-compilada em um único arquivo minificado. A compilação mantém os outros arquivos do pacote, exceto o código já contido nesse arquivo, as declarações de tipos, os mapas de origem e os arquivos README e CHANGELOG da raiz. Projetos com a mesma lista compartilham a compilação.
2. Uma sessão nova ou reiniciada baixa a compilação enquanto clona o repositório e carrega cada extensão diretamente. Uma sessão nunca executa `npm install` nem compila um pacote.
3. Um pacote que não pode ser pré-compilado (por exemplo, um cujo `pi.extensions` usa globs) ainda funciona: a sessão o carrega diretamente dos pacotes instalados, o que leva mais tempo. Se o código de um pacote ler um dos arquivos que a compilação exclui, adicione um filtro `extensions` à entrada: assim, a sessão também o carregará diretamente dos pacotes instalados.
4. Uma sessão iniciada antes da compilação existir é inicializada sem os pacotes do projeto e inicia a compilação; a próxima sessão terá os pacotes.

O Beeuni também instala um conjunto de pacotes do sistema em todas as sessões do harness experimental. Uma entrada do projeto para o mesmo pacote substitui a versão do sistema. Um repositório também pode conter extensões nativas do harness experimental em `.pi/extensions/*.ts`; o harness experimental as carrega sem uma entrada no manifesto.

As extensões são executadas sem uma interface de terminal: ferramentas, hooks e comandos funcionam; widgets exclusivos do terminal não fazem nada.

## `triggers:`

Uma lista de definições de cron, webhook e monitoramento. Cada entrada inicia uma sessão que executa `prompt` como primeira mensagem.

```yaml
triggers:
  - slug: daily-digest
    type: cron
    cron: '0 0 9 * * 1-5'
    prompt: Summarize yesterday's commits.
```

| Campo          | Obrigatório           | Padrão                | Observações                                                                                           |
| -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| `slug`         | sim                   | —                     | `[a-z0-9][a-z0-9_-]{0,127}`, exclusivo entre os gatilhos.                                                   |
| `type`         | sim                   | —                     | `cron`, `webhook` ou `monitor` (experimental).                                                       |
| `prompt`       | sim                   | —                     | Não vazio. Oferece suporte a modelos.                                                                       |
| `name`         | não                   | slug                  | Nome legível.                                                                                          |
| `agent`        | não                   | `default_agent`       | Deve indicar uma chave em `agents:`. Omita para usar `default_agent`; não escreva o literal `default`.      |
| `enabled`      | não                   | `true`                | `false` ignora a entrada.                                                                              |
| `model`        | não                   | resolvido no momento da execução | Formato wire `provider/model`. Fixa a sessão executada nesse modelo. Consulte [Models](/docs/pt/project/models). |
| `session_mode` | não                   | `fresh`               | `fresh`, `reuse`, `pinned` ou `keyed`.                                                               |
| `session_id`   | obrigatório para `pinned` | —                     | Sessão exata para solicitar novamente.                                                                           |

Os gatilhos Cron precisam de exatamente um entre `cron` (uma expressão de 6 campos) ou `run_at` (um timestamp ISO-8601 único), além de `timezone` como nome IANA. Os gatilhos de webhook precisam de `secret_env`, o nome de um segredo que usa a entrega `broker` com o consumidor `connector`. Os gatilhos de monitor precisam de `run` (um comando relativo ao repositório) e `mode` (`poll` ou `stream`), e rejeitam todos os campos de Cron e webhook. Para ver a referência completa dos campos, a configuração de credenciais, os modelos de payload, os endpoints e a estratégia de sessão, consulte [Triggers](/docs/pt/connect/triggers).

## `connectors:`

Uma lista de ferramentas externas que um agente pode chamar. A definição fica no git; as credenciais ficam na plataforma, nunca no manifesto. Consulte [Connectors](/docs/pt/connect/connectors) para entender o modelo conceitual.

```yaml
connectors:
  - slug: gmail-read
    name: Gmail read only
    provider: pipedream
    app: gmail
    authorization_strategy: user
    policies:
      - match: search_email
        action: always_run
```

| Campo                    | Obrigatório | Observações                                                                                                                                                                  |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`                   | sim      | `[a-z0-9][a-z0-9_-]{0,127}`, exclusivo entre os conectores.                                                                                                                  |
| `provider`               | sim      | `pipedream`, `mcp`, `openapi`, `postman`, `graphql`, `http` ou `channel`.                                                                                             |
| `name`                   | não      | Nome de exibição. O padrão é o slug.                                                                                                                                        |
| `authorization_strategy` | não       | `project` ou `user`. O padrão é `project` quando omitido. Uma estratégia de projeto usa as conexões ativas do projeto. Uma estratégia de usuário usa apenas a conexão do membro que está agindo. |
| `enabled`                | não       | O padrão é `true`.                                                                                                                                                    |
| `credential`             | não       | Apenas `shared` é compatível. O modo descontinuado `per_user` gera um erro fatal.                                                                                               |
| `sensitive`              | não       | O padrão é `false`. `true` define `require_approval` como padrão para ações sem correspondência, inclusive leituras. As regras explícitas do projeto e do conector ainda são aplicadas primeiro.          |

Campos específicos do provedor:

| Provedor    | Campo obrigatório | Observações                                                                                                                                      |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `pipedream` | `app`          | `account` é opcional; o padrão é slug.                                                                                                      |
| `mcp`       | `url`          | `transport`: `http` (padrão) ou `sse`.                                                                                                    |
| `openapi`   | `spec`         | Uma URL ou um caminho relativo ao repositório.                                                                                                               |
| `postman`   | `spec`         | Uma URL ou caminho de Collection JSON, um manifesto `.postman/api` ou uma URL de workspace do Postman.                                                      |
| `graphql`   | `endpoint`     | `spec` é opcional (SDL).                                                                                                                     |
| `http`      | `base_url`     | `spec` é opcional.                                                                                                                           |
| `channel`   | `platform`     | `slack`, `teams`, `email` ou `voice`.                                                                                                     |
| `computer`  | —              | Gerenciado pela API. Não é possível declará-lo manualmente. Cada computador conectado é uma de suas contas. Consulte [Computers](/docs/pt/connect/computers). |

Os conectores `channel` raramente precisam de uma entrada escrita manualmente — conectar um canal pelo painel cria uma para você. Consulte [Slack & channels](/docs/pt/connect/slack). Os slugs `beeuni_slack`, `beeuni_teams`, `beeuni_email` e `computer` pertencem à plataforma; usar um deles com outro provedor causa um erro de validação. O conector `computer` é criado quando o primeiro membro conecta um computador, pois os IDs de máquina são identidades do plano de controle da conta e não devem constar no manifesto.

`connectors.auth`: opcional, para provedores diferentes de `pipedream`. `type` é `bearer`, `basic`, `custom`, `api_key`, `oauth1`, `hmac`, `aws_sigv4`, `mtls` ou `none` (padrão). `oauth1` é restrito aos provedores `openapi`, `postman` e `http`. `in` é `header` (padrão), `query` ou `cookie`. `name` é obrigatório quando `type` é `custom` ou `api_key`.

`connectors.policies`: uma lista de pares `{match, action}`. `match` é um padrão glob para nomes de ferramentas. `action` é `always_run`, `require_approval` ou `block`. As políticas pertencem ao conector. Todas as conexões desse conector usam as mesmas políticas.

`policy.default_mode`: uma chave de nível superior, separada de `connectors:`, que define o modo de aprovação de conectores para todo o projeto. Aceita `allow_all` (padrão; toda ferramenta sem correspondência é executada) ou `risk` (exige aprovação para chamadas sem correspondência de escrita e destrutivas). Defina-a com `beeuni connectors policy set --default <risk|allow_all>` — consulte [CLI](/docs/pt/cli).

<a id="channels"></a>

## Canais

A v2 remove `channels:` do esquema. O roteamento de canais para agentes (Slack, Microsoft Teams, e-mail e voz atualmente) é um estado operacional ativo, não uma configuração declarativa. Você o define na página Canais do painel ou por comandos de chat, o mesmo limite que mantém as credenciais fora do git. A conexão de um canal ainda cria uma entrada `connectors` com `provider: channel` para o agente chamar. Consulte [Slack e canais](/docs/pt/connect/slack). A tabela `[[channels]]` da v1 é abordada em [TOML legado](/docs/pt/project/legacy-toml).

## `agents:`

Um mapa de nomes para blocos, indexado pelo nome do agente. Esse mapa serve apenas à governança — ele concede o que um agente pode acessar, nunca o que ele diz ou faz.

Este bloco é **a segunda das duas vinculações**: um principal recebe funções do Beeuni, e um agente também carrega as permissões do Beeuni declaradas aqui. Uma sessão só pode fazer o que ambas permitem. Consulte [Um vocabulário, duas vinculações](/docs/pt/accounts#one-vocabulary-two-bindings).

```yaml
default_agent: beeuni

agents:
  beeuni:
    file: agents/beeuni.md
    connectors: all
    secrets: all
    beeuni_permissions: all
    skills: all

  release-bot:
    file: agents/release-bot.md
    connectors: [github]
    connectors_required: [github]
    beeuni_permissions: [project.gitops.push]
    secrets: [GITHUB_AGENT_TOKEN]
```

| Campo                 | Padrão | Observações                                                                                                                                                                                                     |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _(chave do mapa)_           | —       | `[a-z0-9][a-z0-9_-]{0,127}`, exclusivo por projeto. Sem `file`, também é o nome do arquivo `.md`.                                                                                                           |
| `file`                | `agents/<name>.md` | Caminho relativo ao repositório do `.md` do agente. Consulte [O arquivo do agente](#the-agent-file).                                                                                                                |
| `enabled`             | `true`  | `false` trata o agente como não declarado — a plataforma não o iniciará.                                                                                                                                 |
| `connectors`          | `none`  | Quais slugs de conectores este agente pode chamar. `all` significa todos os conectores.                                                                                                                                   |
| `connectors_required` | `none`  | Obsoleto: analisado e ignorado. A inicialização do sandbox não depende mais de um conector; uma chamada a um conector sem conexão retorna `connector_not_connected` com um link para conectar. Ainda deve ser um subconjunto de `connectors`, quando presente. |
| `secrets`             | `none`  | Quais segredos do projeto este agente recebe como variáveis de ambiente do sandbox. Renomeado de `env` da v1.                                                                                                                   |
| `beeuni_permissions`  | `none`  | Quais permissões do Beeuni (ações do projeto) este agente pode exercer pela CLI, pela API ou pelo git. `all` significa todas as permissões do projeto, ainda limitadas pela função máxima do agente e sem incluir as permissões exclusivas de humanos. `beeuni_cli` é a forma obsoleta: ainda aceita, com um aviso de validação; definir ambas com valores diferentes é um erro. |
| `skills`              | `none`  | Quais habilidades este agente pode carregar.                                                                                                                                                                         |
| `apps`                | `none`  | Quais slugs de Beeuni App este agente pode abrir quando o App está `restricted` ou `private`. `all` significa todos os Apps do projeto. Consulte [Agentes e Apps](/docs/pt/feature-flags/apps#agents-and-apps). |
| `tools`               | `all`   | Quais ferramentas este agente pode usar: ferramentas do harness, do Beeuni e do projeto. `all`, `none`, uma lista (somente essas) ou `{ exclude: [...] }` (todas, exceto essas). A forma de mapa anterior `{ bash: false }` ainda funciona. Diferentemente das concessões acima, se `tools` for omitido, todas as ferramentas serão permitidas. Consulte [Quem pode usar cada ferramenta](/docs/pt/project/tools#who-may-use-which-tool). |
| `repository_access` | `true` | Se novas sessões recebem o repositório do projeto. `false` desativa a entrega do repositório e o acesso a ele por meio das credenciais da sessão. As sessões existentes mantêm a política salva. |

A v2 nega por padrão: se `connectors`, `secrets`, `beeuni_permissions`, `skills` ou `apps` for omitido em um agente declarado, o valor será `none`. Conceda explicitamente todas as permissões necessárias ao agente, como faz o agente `beeuni` inicial acima. Um projeto que migra da v1 precisa conceder tudo novamente manualmente — na v1, o padrão de `env` (segredos), quando omitido, é `all`, o oposto da v2.

`connectors_personal` continua sendo um alias de entrada obsoleto para
`connectors_required`. Novos manifestos devem usar `connectors_required`. O valor `authorization_strategy` do conector determina se a autorização pertence ao projeto ou ao membro.

As concessões de `beeuni_permissions` vêm de um conjunto fixo de permissões no escopo do projeto (`project.read`, `project.gitops.push`, `project.gitops.merge`, `project.gitops.ref.any`, `project.trigger.*`, `project.secret.*`, `project.connector.*` e outras). As permissões no escopo da conta — `member.*`, `billing.*`, `project.create` — nunca podem ser concedidas a um agente. Execute `beeuni validate --scopes` de dentro de uma sessão para exibir a lista atual de permissões concedíveis.

<a id="the-agent-file"></a>

### O arquivo do agente

`agents.<name>.file` indica o `.md` do agente, relativo à raiz do repositório.

```yaml
agents:
  support:
    file: agents/support.md
```

- O caminho deve terminar em `.md`.
- O caminho não pode começar com `/` nem `-`. Não pode conter um segmento `.` ou `..`, nem um segmento vazio.
- Cada segmento pode conter apenas letras, dígitos, `_`, `-`, `.` e espaços.
- Quando `file` é omitido, o Beeuni lê `agents/<name>.md` e depois `.beeuni/opencode/agents/<name>.md`. Quando `opencode.config_dir` está definido, o segundo caminho é `<config_dir>/agents/<name>.md`.
- Quando o painel salva um agente que tem um `.md`, ele grava `file` com esse caminho.
- A API recusa uma solicitação que altere `file` (`400`, código `invalid_config`). Para mover um agente, mova seu `.md` e atualize `file` em `beeuni.yaml` no mesmo commit.

`beeuni validate` e a verificação de mesclagem da solicitação de alteração rejeitam um `file` inválido com um erro em `agents.<name>.file`.

<a id="when-config-changes-take-effect"></a>

## Quando as alterações de configuração entram em vigor

- Uma edição de manifesto, `agents/`, `skills/` ou do diretório de configuração do harness padrão só entra em vigor depois que uma solicitação de alteração é mesclada em `main`. As sessões e os gatilhos leem a ramificação padrão, não as ramificações de sessão.
- Uma alteração no cron ou no webhook de um gatilho é detectada pelo agendador em segundos após a mesclagem.
- Uma alteração na imagem do sandbox ou no hardware recria o snapshot. A nova especificação se aplica à próxima sessão, não à atual.
- Uma alteração no valor de um segredo no painel é resolvida no momento da criação do sandbox. Ela se aplica à próxima sessão, não a uma sessão em execução.

<a id="round-trip-rules"></a>

## Regras de ida e volta

As edições no painel são operações de leitura-modificação-gravação no arquivo que declara a entrada: `beeuni.yaml` ou um [arquivo importado](#imports). Para manter as diferenças organizadas entre as edições na interface e durante a sessão:

1. Mantenha `beeuni_version` como a primeira chave.
2. Dentro de uma entrada de gatilho, ordene os campos `slug`, `name`, `type`, `agent`, `enabled`, depois os campos específicos do tipo e, por último, `prompt`.
3. Se você adicionar um gatilho de webhook antes de definir o segredo, liste o nome do segredo em `env.optional`. Mantenha o gatilho `enabled: false` até inserir o valor.

<a id="repository-access"></a>

### Acesso ao repositório

Defina `agents.<name>.repository_access` como `false` para agentes que não precisam dos arquivos de origem do projeto.
Eles ainda podem criar arquivos no sandbox e usar as ferramentas, os segredos e os conectores concedidos.
Defina como `true` para agentes que precisam do repositório. As permissões do Git permanecem separadas.
Altere essa configuração no editor do agente em **Workspace → Project repository access**.
A configuração se aplica a novas sessões. As sessões existentes mantêm a política salva, inclusive após a substituição do runtime.

```yaml
agents:
  support:
    repository_access: false
  engineer:
    repository_access: true
```

O campo obsoleto `workspace` continua legível: `branch` significa `true`, e `runtime` significa `false`.
As configurações legadas de `read` continuam rejeitando a criação de sessões até que você substitua o campo por um booleano explícito.
Não existe um modo de repositório somente leitura. Campos antigos e novos conflitantes são rejeitados.
O editor e o SDK enviam `repository_access`. Para acesso desativado, a API também armazena `workspace: runtime` como um espelho de compatibilidade. Isso preserva a restrição para réplicas de API mais antigas durante a implantação ou a reversão. As leituras da API omitem o espelho. Manifestos escritos manualmente usando apenas `repository_access` exigem a API atualizada.