# orboto documentation (/)



orboto brings your projects, tickets, docs, time tracking and automation
together in one place - and treats AI agents as real team members, with
the same permissions, the same workflows and the same accountability as
everyone else. Whatever the web app can do, your automations and agents
can do too: one system, every surface.

Run it as a managed cloud workspace, or self-host it and keep every byte
on your own infrastructure - same product, your choice.

<Cards>
  <Card title="Getting started" href="/getting-started" description="Sign in, learn the screen, create your first project and ticket." />

  <Card title="User guide" href="/user-guide" description="Every feature, explained task by task." />

  <Card title="Admin guide" href="/admin" description="Accounts, permissions, security, integrations, operations." />

  <Card title="orboto cloud" href="/cloud" description="The managed edition - we run it, you use it." />

  <Card title="Self-hosting" href="/self-hosting" description="Your hardware, your data - up and running with Docker." />

  <Card title="API & CLI" href="/api-cli" description="The REST API behind every surface, the CLI, the OQL query language." />

  <Card title="Agents & AI" href="/agents-ai" description="Connect AI tools via MCP, route work to agents, run autonomous fleets." />

  <Card title="Integrations" href="/integrations" description="Git hosting, n8n, chat notifications, calendars, SCIM." />
</Cards>

## Built to be read by AI, too [#built-to-be-read-by-ai-too]

These docs meet your tools halfway: every page has a raw-Markdown twin
(page menu: Copy page, View as Markdown, Open in ChatGPT or Claude), and
the whole documentation is indexed for LLMs at [`/llms.txt`](/llms.txt)
and [`/llms-full.txt`](/llms-full.txt). Paste a page into any assistant -
or let it fetch the docs itself.


# Admin guide (/admin)



Everything an administrator configures lives under **Admin** in the
sidebar; each guide below walks one area end to end.

<Cards>
  <Card title="Users, roles and permissions" href="/admin/identity/users-and-roles" description="The permission model, accounts, bots, sessions, GDPR." />

  <Card title="API keys" href="/admin/identity/api-keys" description="Programmatic access, agent profiles, key hygiene." />

  <Card title="Single sign-on" href="/admin/identity/sso" description="OIDC and SAML against your identity provider." />

  <Card title="Two-factor authentication" href="/admin/identity/two-factor" description="TOTP, passkeys, recovery codes, enforcement." />

  <Card title="AI providers" href="/admin/ai/ai" description="The provider behind every AI feature." />

  <Card title="Inbound email" href="/admin/email/inbound-email" description="Turn incoming mail into tickets - webhook, IMAP or SMTP." />

  <Card title="Webhooks" href="/admin/data/webhooks" description="Signed event deliveries to your systems." />

  <Card title="Git integration" href="/admin/data/git-integration" description="Connect repositories; commits link to tickets." />

  <Card title="Import" href="/admin/data/import" description="Bring work over from other tools or CSV." />

  <Card title="Backups" href="/admin/operations/backup" description="Scheduled archives and restores." />

  <Card title="Audit and compliance" href="/admin/operations/audit-and-compliance" description="Audit log, tamper evidence, GDPR tooling." />

  <Card title="Email templates" href="/admin/email/email-templates" description="Customize every outbound email, per language." />

  <Card title="Alerts and SLA" href="/admin/operations/alerts-and-sla" description="Automatic warnings and response-time policies." />

  <Card title="Translations" href="/admin/operations/translations" description="Machine translation with review." />

  <Card title="Federation" href="/admin/operations/federation" description="Sync projects across instances." />

  <Card title="Agents administration" href="/admin/ai/agents" description="Presence, routing labels, pause switches, agent rules." />

  <Card title="System settings" href="/admin/operations/system-settings" description="Registration, domains, timezone, kill switches." />

  <Card title="Licensing" href="/admin/operations/licensing" description="Editions and license keys." />
</Cards>


# The agent skill (/agents-ai/agent-skill)



For agents that do not speak MCP - headless coding agents, CI bots,
scripts - orboto ships a **skill**: a packaged instruction set plus a
wrapper that teaches an agent the full orboto workflow over the REST API.

## What it covers [#what-it-covers]

The complete working loop: starting a session (which delivers the binding
workspace rules), finding and claiming tickets, the one-commit-per-ticket
discipline, commenting, time tracking, moving tickets through review, and
closing with evidence. The skill mirrors what the MCP server exposes, so
agents on either surface behave consistently.

The same loop looks like this from the [CLI](/api-cli/cli-usage) -
the skill's operation reference maps each of its steps to one of these
calls:

```bash
orboto session-start --project ACME
orboto claim ACME-42
orboto comment ACME-42 "root cause: session TTL was set in minutes, not seconds"
orboto close ACME-42 --comment "fixed and verified by the test suite"
```

## Installing [#installing]

1. In orboto, open your **Profile** and find the **AI agent skill**
   card (the same card also appears under **Admin → System settings**
   for an operator setting this up for a whole team).
2. Select **Download**. You get a zip archive containing the skill's
   instruction file, its companion reference files, and a
   `.env.sample` already filled in with your instance's URL - so you
   only need to add a token, not type the URL by hand.
3. Unzip it into your agent's skill or instruction directory (where
   that lives depends on your agent runtime - check its docs for where
   it looks for skills or custom instructions).
4. Copy `.env.sample` to `.env` inside the unzipped folder and paste in
   an API key minted for the agent's **bot identity** (not a human
   account) - see [API keys](/admin/identity/api-keys) for how to
   mint one scoped to a service account.
5. Run whatever smoke-test operation the skill documents (typically an
   identity check) to confirm the agent can actually reach your
   instance and authenticate before relying on it for real work.

The [CLI](/api-cli/cli) covers the exact same operations as single
commands and is the recommended companion - the skill's operation
reference maps each step to a CLI call, so you can debug a failing skill
operation by running the equivalent CLI command directly and seeing
which one actually breaks.

{/* screenshot: the AI agent skill card on the Profile page with the Download button */}

**Staying current.** The skill evolves alongside orboto - re-downloading
later picks up newer operations and reference updates. Repeat the
download step above whenever you upgrade your orboto instance to a
meaningfully newer version, the same way you'd update any other
dependency.

## Rules delivery [#rules-delivery]

The first session call returns the workspace's agent rules **and** a
short `rulesHash`. From then on, every session call sends that hash back
as `knownRulesHash`:

* If the hash still matches the workspace's current rules, the response
  comes back with `rulesUnchanged: true` and **no rules text at all** -
  the agent already has them, so there's nothing to resend. This is why
  starting a session on every ticket doesn't mean re-reading the whole
  rulebook every time.
* If an admin changed the rules since your last session, the hash won't
  match. The response includes `rulesUnchanged: false` **and** the full,
  current rules text - the agent picks it up automatically on its very
  next session call, with no separate "check for updates" step needed.

If an agent's own context gets reset or compacted and it loses track of
whether it actually has current rules, it can force a full resend
regardless of hash match (`--force-rules` on the CLI, or the equivalent
skill/MCP option) - useful after anything that might have dropped
context, since assuming stale rules are current is worse than an extra
few hundred tokens.

Rules can also target **agent kinds** and **model tiers**, so a
workspace can hand different agents appropriately-scoped instructions
instead of one rulebook for everyone - see
[Agents administration](/admin/ai/agents) for how an admin sets
that up.

For example, a coding agent running on a frontier-tier model identifies
itself via env vars before starting a session:

```
ORBOTO_AGENT_KIND=coding
ORBOTO_MODEL_TIER=frontier
```

`orboto session-start` (or the equivalent MCP/skill call) then returns
the rule variant scoped to that kind and tier, alongside the requester's
in-progress work and current timer state.

## Work routing awareness [#work-routing-awareness]

An agent following the skill is expected to respect the same routing
labels a human sees on a board: pull work with
[`work-next`](/agents-ai/work-routing) rather than grabbing any
open ticket, skip `human`-labeled tickets, and prefer `agent:<tag>`
tickets that match its own lane. See
[Work routing and fleets](/agents-ai/work-routing) for the full
model and labeling examples.

## Troubleshooting [#troubleshooting]

| Symptom                                                                | Likely cause                                                                                                                                                                                                            |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The agent never sees the rules update after an admin changes them      | Rules are confirmed by hash on each session call, not pushed. Make sure the agent actually calls `session-start` (or the MCP/skill equivalent) at the start of every work session rather than reusing a cached session. |
| `claim` or `comment` returns `401`/`403`                               | The bot identity's API key is missing, expired, or lacks the permission for that project - check [API keys](/admin/identity/api-keys) and the bot's project membership/role.                                            |
| The agent picks up a ticket meant to stay human-only                   | Confirm the ticket carries the `human` label - see [Work routing](/agents-ai/work-routing#routing-labels) - and that the agent's loop actually pulls via `work-next` instead of scanning the raw ticket list.           |
| Rules look scoped wrong (e.g. a "frontier" ruleset on a smaller model) | Check `ORBOTO_AGENT_KIND` / `ORBOTO_MODEL_TIER` (or the MCP/skill equivalents) are set correctly for that agent instance before it calls session-start.                                                                 |


# External agent tokens (/agents-ai/external-agents)



## What an external agent token is [#what-an-external-agent-token-is]

Most AI clients that talk to orboto do so as a **workspace member** - a
human's own account, or a [bot identity](/admin/identity/users-and-roles)
created for automation. Either way, the connection acts with a real
project membership and a real permission set, exactly like a person using
the app (see [Connecting an AI client to your
workspace](/integrations#connecting-an-ai-client-to-your-workspace)).

An **external agent token** is a different, narrower kind of credential, for
a case that doesn't fit that model: a third-party AI agent harness - a
background coding agent built into an external tool, for example - that
you want to give limited read access to specific orboto data, without making
it a member of any project. It has no project membership and no role. What
it can read is defined entirely by an explicit allowlist of resource
patterns an administrator grants when the token is created.

## How it differs from a bot API key [#how-it-differs-from-a-bot-api-key]

|             | Bot API key (`orb_*`)                                                                | External agent token (`xag_*`)                                                                                             |
| ----------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Identity    | A real user account with project membership                                          | No user account, no project membership                                                                                     |
| Access      | Whatever its role's permissions allow, across every project it's a member of         | Only the specific `orboto://` resource patterns listed on the token                                                        |
| Can write?  | Yes, if its role permits it                                                          | No - read-only by design                                                                                                   |
| Issued from | The bot user's own **Profile → API keys**                                            | The admin API, by a super-admin, naming an agent and its allowed scopes directly                                           |
| Typical use | An automation that should act like a team member - create tickets, comment, log time | A third-party client you want to hand a narrow, revocable read window into your workspace, without onboarding it as a user |

If the integration should behave like a teammate - creating tickets,
commenting, moving work through statuses - use a bot identity and a regular
API key instead, the same as the [n8n integration](/integrations/n8n)
or the [MCP server](/agents-ai/mcp) does. Reach for an external agent
token only when you specifically want to hand out scoped, read-only
visibility to a client you don't want as a full member.

## The token format [#the-token-format]

An external agent token is a random secret prefixed `xag_` (distinct from
the `orb_` prefix on ordinary API keys, so orboto's authentication layer can
tell the two apart at a glance). Only its SHA-256 hash is stored - the
plaintext secret is shown to the administrator who created it exactly once,
at creation time, and never again.

## Managing tokens [#managing-tokens]

Token management is an administrator action, gated behind the
`admin:system:write` permission (list-only access needs
`admin:system:read`). There is currently no admin UI page for this - manage
tokens through the REST API directly, for example with `curl`.

### Grant a token [#grant-a-token]

```bash
curl -X POST https://your-orboto-host.example.com/api/admin/external-agents \
  -H "Authorization: Bearer orb_<an admin's API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "ACME support bot",
    "allowedScopes": ["orboto://ticket/ACME-*", "orboto://project/ACME"]
  }'
```

```json
{ "id": "5b1a...", "token": "xag_3f9c2a1e..." }
```

Copy the `token` value somewhere safe immediately - this response is the
only time orboto ever returns the plaintext secret. Hand it to whatever
external client will use it (however that client expects a bearer
credential configured).

### List tokens [#list-tokens]

```bash
curl https://your-orboto-host.example.com/api/admin/external-agents \
  -H "Authorization: Bearer orb_<an admin's API key>"
```

Each entry shows the agent's name, its scope list, when it was created and
last used, and whether it's been revoked - but only the first 12 characters
of the token (`apiKeyPrefix`), enough to recognize which secret a client is
presenting without ever exposing the full value again.

### Revoke a token [#revoke-a-token]

```bash
curl -X DELETE https://your-orboto-host.example.com/api/admin/external-agents/5b1a... \
  -H "Authorization: Bearer orb_<an admin's API key>"
```

Revocation is immediate and permanent. There's no un-revoke - grant a fresh
token if the integration needs to reconnect later.

## The scope model: what a token can and cannot reach [#the-scope-model-what-a-token-can-and-cannot-reach]

`allowedScopes` is a list of `orboto://` resource patterns - the same URI
scheme used by [MCP resources](/agents-ai/mcp) elsewhere in orboto.
Each pattern is either an exact resource address or ends in a single
trailing `*` wildcard:

* `orboto://project/ACME` - exactly that one project.
* `orboto://ticket/ACME-42` - exactly that one ticket.
* `orboto://ticket/ACME-*` - every ticket in the `ACME` project, current and
  future, without listing them one by one.

Anything not covered by at least one pattern on the token is invisible to
it - there's no implicit access to "the rest of the workspace" the way a
project member's role would grant. A token scoped to `orboto://ticket/ACME-*`
can't see `WEB` project tickets, docs, milestones, or anything else outside
what its patterns literally cover, no matter how narrow or broad you make
the list.

## Current status [#current-status]

Provisioning and revoking external agent tokens through the admin API above
is available today. Connecting a specific external client to consume a
token - the piece where the client actually presents an `xag_*` token
against a live orboto endpoint and gets back the scoped data - is still
being finalized on orboto's side; there's no client-facing connection guide
to publish yet. If you're evaluating this for an integration, provision a
token now to reserve the scope you want, and check back for the connection
steps once that path ships.

## Troubleshooting [#troubleshooting]

| Symptom                                                    | Likely cause                                                                                                                                               |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /admin/external-agents` returns 403                  | The calling account doesn't hold `admin:system:write` - only a super-admin (or an admin role with that specific permission) can create or revoke tokens.   |
| `allowedScopes` rejected with a validation error           | Every entry must start with `orboto://`. A bare resource name without the scheme prefix (e.g. `ticket/ACME-42`) is rejected, not silently corrected.       |
| Lost the plaintext token after creation                    | It can't be recovered - the stored value is a one-way hash. Revoke the old token and grant a new one.                                                      |
| A token still shows as active after you meant to remove it | Confirm you deleted the right row - `GET /admin/external-agents` lists every token's `id`; match on `agentName` or `apiKeyPrefix` before calling `DELETE`. |


# Agents & AI (/agents-ai)



orboto treats AI agents as first-class team members: they authenticate with
their own bot identities, obey the same permissions as humans, and get
purpose-built surfaces.

## The agent surfaces [#the-agent-surfaces]

* **MCP server** - connect Claude, Cursor or any MCP client to your
  workspace with structured tools and resources ([setup](/agents-ai/mcp)).
* **The CLI** - the same API for headless agents and scripts
  ([reference](/api-cli/cli)).
* **Work routing** - label a ticket `agent:<tag>` to prefer a specific
  agent, `human` to lock agents out entirely; per-bot and workspace-wide
  autonomy pause switches live under Admin.
* **Work sessions** - agents claim tickets through atomic leases (one
  active implementation per ticket workspace-wide), pull the best ready
  ticket with `work-next`, and review lanes pull tickets waiting for
  review - never their own work.
* **In-app AI assistant** - the chat inside orboto that operates the
  workspace for you ([guide](/user-guide/ai-assistant)).

<Cards>
  <Card title="MCP server setup" href="/agents-ai/mcp" description="Local proxy or self-hosted HTTP, OAuth, resources, prompts." />

  <Card title="The agent skill" href="/agents-ai/agent-skill" description="The packaged REST workflow for autonomous, non-MCP agents." />

  <Card title="Work routing and fleets" href="/agents-ai/work-routing" description="Route work by label, guard it with leases and pauses." />
</Cards>


# MCP server setup (/agents-ai/mcp)



The `@orboto/mcp` package exposes orboto as a [Model Context Protocol](https://modelcontextprotocol.io/) server, so any MCP-aware AI client (Claude Desktop, Cursor, GitHub Copilot Chat, Codex CLI, custom agents) can read and modify tickets, docs, milestones, and timers as a regular orboto user.

You don't need this for the agent skill - that one talks to orboto's REST API directly and is downloadable from your instance. MCP is the right surface when the client speaks MCP natively and you want a structured tool/resource/prompt interface.

Every call goes through the orboto REST API as the API-key owner, so all permission and ACL rules are enforced exactly as for a logged-in user.

## Connect a client [#connect-a-client]

### Prerequisites [#prerequisites]

* orboto instance reachable from wherever the MCP process runs (laptop for Local-Proxy, the same host for Self-Hosted-Inline).
* Super-admin access to mint API keys, or a project admin who can do it for you.
* For Self-Hosted-Inline: nothing extra - `/mcp` is routed through the existing orboto host by the web container's nginx. The legacy dedicated `mcp.<orboto-host>` subdomain is still supported via the `SERVICE_FQDN_MCP_3100` opt-in.

### Mint an MCP API key [#mint-an-mcp-api-key]

Every MCP session authenticates with an orboto API key that has the `mcp:use` scope. The key inherits the owner's project memberships and global roles - the MCP surface enforces them, it does not bypass them.

1. Decide which user account the MCP session should act as. **Recommended**: a dedicated bot user (System Settings → Users → New user → "Service account (bot)"). Bots authenticate via API keys exclusively, can be added to projects with a custom role, and never collide with a human's session log.
2. Open the user's profile (Profile menu for yourself, Admin → Users → Edit → API keys for a bot account).
3. **Generate API key** → name it (e.g. `claude-desktop`), pick an optional expiry, save.
4. Copy the `orb_…` token. **It is shown once** - store it in your client's secret manager.

If the user lacks `mcp:use`, the API rejects with 403 and the MCP preflight surfaces the error to stderr before the transport spins up.

{/* screenshot: the Generate API key dialog with the mcp:use scope */}

### Pick a delivery mode [#pick-a-delivery-mode]

| Mode                                   | Transport                      | Who runs the process                          | Auth                                                    | Use when                                                                                                |
| -------------------------------------- | ------------------------------ | --------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Local-Proxy**                        | stdio                          | Each operator's laptop                        | API key in env                                          | Single user, talking to a remote orboto instance from one client                                        |
| **Self-Hosted-Inline (OAuth)**         | HTTP (Streamable per MCP spec) | One container alongside the orboto deployment | OAuth 2.1 + PKCE via the client's built-in connector UI | Default for Claude Desktop / Cursor / VS Code - operator pastes the `/mcp` URL, browser handles consent |
| **Self-Hosted-Inline (static Bearer)** | HTTP                           | Same                                          | Per-request `Authorization: Bearer orb_*` header        | Headless / CI bots that can't run an interactive browser flow                                           |

Both modes use the same `@orboto/mcp` build - only the transport and auth model differ. Pick Local-Proxy for a quick personal setup against a remote instance; pick Self-Hosted-Inline when you're running the orboto deployment yourself and want every operator to connect through one shared URL.

## Local-Proxy setup (stdio) [#local-proxy-setup-stdio]

The MCP process runs on your laptop, spawned by the AI client over stdio. It authenticates one of two ways:

* **OAuth login - recommended for people.** Omit `ORBOTO_API_KEY`. On first use the proxy runs a browser-assisted loopback OAuth flow through your workspace login (which is your SSO login when SSO is configured), then caches a short-lived, self-refreshing session at `~/.config/orboto/mcp-oauth.json` (`0600`). No token pasted, nothing long-lived. Set `ORBOTO_MCP_NO_BROWSER=1` on headless hosts to print the authorization URL instead of opening a browser; `ORBOTO_AUTH=oauth` forces this path even when a key is present.
* **API key - service accounts / CI.** Embed an `orb_…` key (below). Best for headless machines with no interactive user.

### Recommended (people) - OAuth login, no token [#recommended-people---oauth-login-no-token]

```json
{
  "mcpServers": {
    "orboto": {
      "command": "npx",
      "args": ["-y", "@orboto/mcp"],
      "env": {
        "ORBOTO_API_URL": "https://orboto.example.com/api",
        "ORBOTO_MCP_CLIENT": "claude-desktop"
      }
    }
  }
}
```

### API key - `npx @orboto/mcp` [#api-key---npx-orbotomcp]

Since `@orboto/mcp` is published to npm, the AI client can spawn the package directly without a local clone:

```json
{
  "mcpServers": {
    "orboto": {
      "command": "npx",
      "args": ["-y", "@orboto/mcp"],
      "env": {
        "ORBOTO_API_URL": "https://orboto.example.com/api",
        "ORBOTO_API_KEY": "orb_…",
        "ORBOTO_MCP_CLIENT": "claude-desktop"
      }
    }
  }
}
```

Pin to your server's exact version (`"@orboto/mcp@0.89.1"`) for reproducible setups; use `@latest` only when your orboto host always runs the most recent release. On mismatch (package newer than server) some newer tools surface 404 at call time - the older ones keep working.

### Claude Desktop [#claude-desktop]

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) with either JSON block above. Quit and relaunch Claude Desktop - the orboto server appears in the connector menu, and expanding it shows the connected tool list.

### Cursor [#cursor]

`.cursor/mcp.json` in the workspace root (or `~/.cursor/mcp.json` for global):

```json
{
  "mcpServers": {
    "orboto": {
      "command": "npx",
      "args": ["-y", "@orboto/mcp"],
      "env": {
        "ORBOTO_API_URL": "https://orboto.example.com/api",
        "ORBOTO_API_KEY": "orb_…",
        "ORBOTO_MCP_CLIENT": "cursor"
      }
    }
  }
}
```

Cursor reads the file on every chat session start; no restart required after editing.

### GitHub Copilot Chat (VS Code) [#github-copilot-chat-vs-code]

`.vscode/mcp.json`:

```json
{
  "servers": {
    "orboto": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@orboto/mcp"],
      "env": {
        "ORBOTO_API_URL": "https://orboto.example.com/api",
        "ORBOTO_API_KEY": "orb_…",
        "ORBOTO_MCP_CLIENT": "vscode-copilot"
      }
    }
  }
}
```

`ORBOTO_MCP_CLIENT` is purely a User-Agent suffix - handy for filtering the API audit log by client.

### Codex CLI [#codex-cli]

Codex (the OpenAI coding agent / VS Code ChatGPT extension) reads TOML from `~/.codex/config.toml`. Add an `[mcp_servers.orboto]` table pointing at the stdio local-proxy - **stdio is the recommended transport for Codex**; see [Client compatibility](#client-compatibility) for why HTTP+OAuth is rougher on Codex today.

```toml
[mcp_servers.orboto]
command = "npx"
args = ["-y", "@orboto/mcp"]
env = { ORBOTO_API_URL = "https://orboto.example.com/api", ORBOTO_API_KEY = "orb_…", ORBOTO_MCP_CLIENT = "codex" }
```

The `orb_…` value is a service-account API key (see [Mint an MCP API key](#mint-an-mcp-api-key)) - it gives Codex zero OAuth churn on headless/CI hosts. For a personal login instead, omit `ORBOTO_API_KEY` and the proxy runs the same browser-assisted OAuth flow as the other clients above (set `ORBOTO_MCP_NO_BROWSER=1` on a headless box to print the URL).

Instead of hand-editing the TOML you can run `codex mcp add` from the CLI (see `codex mcp add --help` for the current flag syntax) - it writes the same `[mcp_servers.orboto]` block. Restart Codex after either method; the orboto tools appear in its MCP list.

## Self-Hosted-Inline setup (HTTP) [#self-hosted-inline-setup-http]

One MCP container per orboto deployment, listening on port 3100 internally. The web container's nginx proxies `/mcp` on the main host straight to it - same pattern as `/api` → `api:3000`. Each MCP client supplies its own Bearer token per session, so multiple operators share one container without sharing keys.

Operators get **one URL, one cert, one DNS record** per deployment. The MCP server lives at `https://<orboto-host>/mcp` (where `<orboto-host>` is whatever your existing API/web lives on - e.g. `orboto.example.com`). No separate subdomain to manage.

### Spin up the container [#spin-up-the-container]

The MCP service ships alongside the standard orboto deployment:

```bash
docker compose up -d mcp
```

The container reads:

| Variable               | Required | Effect                                                                |
| ---------------------- | -------- | --------------------------------------------------------------------- |
| `ORBOTO_API_URL`       | yes      | Base URL of the orboto API. Inside compose, that's `http://api:3000`. |
| `ORBOTO_MCP_TRANSPORT` | yes      | Set to `http`. The container default already has this.                |
| `ORBOTO_MCP_PORT`      | no       | Listen port (default `3100`).                                         |

On Coolify, the web container's nginx already routes `/mcp` → `mcp:3100` so the MCP server is reachable on the main orboto URL the moment you deploy. **No subdomain to configure**.

If you do want a dedicated MCP subdomain (e.g. `mcp.<orboto-host>`) - handy for clients that don't follow path-based routing well - set the Coolify magic variable `SERVICE_FQDN_MCP_3100` to a hostname; Coolify allocates the cert + DNS. Both routes coexist.

### OAuth via the connector UI (default) [#oauth-via-the-connector-ui-default]

1. Claude Desktop → **Settings → Connectors → Add custom connector**
2. Paste `https://<orboto-host>/mcp`
3. Browser opens to orboto, prompts you to log in if not already, then shows a consent screen ("Authorize Claude Desktop")
4. Click **Authorize** → returns to Claude Desktop. The tool list populates within seconds.

{/* screenshot: the orboto MCP consent screen with the identity picker */}

Cursor and VS Code do the same flow under **Settings → Tools and Integrations → Add MCP server** (Cursor) or `MCP: Add Server` from the command palette (VS Code) - just paste the URL.

No API key, no operator-pre-config - each operator authorizes once per AI client install, and the resulting token rotates automatically.

**Which identity you get.** This matters more than the transport. OAuth via `/mcp` signs you in as your own orboto user, and the consent screen lets you **choose the identity the connection acts as**: yourself (the default - every ticket, comment, timer, and doc is attributed to you, with your exact permissions and ACLs), or an **agent account you own**. Choosing an agent account attributes every action, timer and time entry of that connection to the agent instead of you - your personal timer and timesheet stay untouched - and the connection runs with the agent's own permissions. The grant is audited with both identities, `whoami` reports both, Profile → Connected AI clients shows an "acting as" badge, and the delegation dies immediately if the agent account is deactivated, re-owned, or you are deactivated. A static `orb_…` Bearer token (below) acts as **whatever account minted the key** - still the right choice for headless bots and CI that never see a browser. Same tool surface either way; only the acting identity differs.

### Static Bearer for CI / headless bots [#static-bearer-for-ci--headless-bots]

```json
{
  "mcpServers": {
    "orboto": {
      "type": "streamable-http",
      "url": "https://orboto.example.com/mcp",
      "headers": {
        "Authorization": "Bearer orb_…"
      }
    }
  }
}
```

The `orb_*` API key path stays supported alongside OAuth - the `/mcp` endpoint accepts both. Use it for service-account bots where there's no interactive user to walk through the consent screen.

If you opted into the dedicated subdomain via `SERVICE_FQDN_MCP_3100`, swap the URL for `https://mcp.orboto.example.com/mcp` - both endpoints work identically.

### Health probe [#health-probe]

`GET /health` on the MCP container returns `{"status":"ok"}` without auth. It's used by the docker-compose healthcheck; it's intentionally NOT exposed through the `/mcp` nginx route (the public path passes only `/mcp` through). To probe end-to-end, POST an `initialize` request:

```bash
curl -X POST https://orboto.example.com/mcp \
  -H "Authorization: Bearer orb_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# → returns the server's capabilities + protocol version
```

## Tools, resources, and prompts [#tools-resources-and-prompts]

### What's exposed [#whats-exposed]

* **A curated tool manifest by default** - the measured high-frequency set (\~28 tools: the ticket loop, search + OQL query, time tracking, doc read, milestone create, session/identity) plus the two escape-hatch tools below. Most MCP clients load EVERY tool schema at connect time; the curated manifest costs them \~9k tokens instead of \~47k for the full set. The full named-tool manifest stays one opt-in away (see below).
* **The escape hatch: the ENTIRE REST API stays reachable.** `orboto_api_search` finds any endpoint + its schema in the live OpenAPI spec; `orboto_api_call` executes it through the API's full permission chain. See below for a worked example.
* **The full named-tool manifest (\~171 tools) is one opt-in away** - see "Choosing the toolset" below.
* **4 resources** - `ticket`, `doc`, `project`, `search` - fetchable by URI for clients that prefer the resource pattern over tool calls.
* **5 prompts** - `plan-sprint`, `triage-my-tickets`, `summarize-project`, `estimate-ticket`, `find-duplicates`. Pre-baked instruction templates the client can invoke with parameters.

### Choosing the toolset [#choosing-the-toolset]

| Mode                | Tools | Connect-time schema cost (measured 2026-08-10) | How to select |
| ------------------- | ----- | ---------------------------------------------- | ------------- |
| `curated` (default) | 28    | 37.5k chars, \~9.4k tokens                     | nothing to do |
| `full`              | 171   | 189.7k chars, \~47.4k tokens                   | see below     |

* **HTTP (remote) clients**: append `?toolset=full` to the endpoint URL - e.g. `claude mcp add --transport http orboto https://<host>/mcp?toolset=full` - or send an `x-orboto-toolset: full` header. Per-connection; no server access needed.
* **stdio (Local-Proxy)**: set `ORBOTO_MCP_TOOLSET=full` in the server's `env` block.
* **Server-wide default**: an operator can set `ORBOTO_MCP_TOOLSET=full` on the MCP container to flip the default for every connection that doesn't choose explicitly.

Deferred-loading clients (clients with tool search) pay almost nothing for the full manifest - `full` is a fine choice there. Eager-loading clients (Claude Desktop, Cursor, Codex) pay the whole manifest on every conversation turn - stay on `curated` unless you really use the long tail as named tools.

### The escape hatch (api\_search + api\_call) [#the-escape-hatch-api_search--api_call]

Anything not in the curated manifest is still one search away. Worked example - trigger a backup (an admin tail operation with no named tool in the curated set):

1. `orboto_api_search` with `{"query": "trigger backup"}` returns, among others:
   `POST /admin/backup/run [admin:backup:write] - ...`
2. Optional: `orboto_api_search` with `{"path": "/admin/backup/run", "method": "POST"}` returns the full request/response schema.
3. `orboto_api_call` with `{"method": "POST", "path": "/admin/backup/run", "body": {...}}` executes it. The response envelope carries the inner HTTP status + body verbatim - a `403` means the API key lacks the permission, exactly as it would on a direct REST call.

Guardrails: the proxy only dispatches to routes that exist in the live OpenAPI spec, refuses auth/OAuth/setup/webhook/transport paths outright, is rate-limited (120/min), and never exceeds the caller's own permissions - enforcement happens in the API's route handlers, not in the MCP layer.

### Live resource subscriptions - which clients benefit [#live-resource-subscriptions---which-clients-benefit]

The server pushes `notifications/resources/updated` for `orboto://ticket/<key>`, `orboto://doc/<id>`, `orboto://project/<key>`, `orboto://timer`. AI clients that subscribe to a resource get notified the moment the underlying ticket / doc / etc. changes - no polling.

The catch: only AI clients with an **always-on connection AND their own event loop** can act on these pushes. Most interactive chat UIs don't have that shape. Quick table:

| Client                                                        | Benefits from live push? | Why                                                                                                                                             |
| ------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Autonomous agent loops (persistent worker processes, daemons) | **Yes**                  | Own event loop; subscribes to resources and reacts between turns.                                                                               |
| Cursor Background Agent Mode                                  | **Yes**                  | Runs in the background, holds subscriptions, reacts on events.                                                                                  |
| Custom MCP bots (a chat-tool bridge, a bot process)           | **Yes**                  | Persistent process, full control over the connection.                                                                                           |
| **Claude Desktop**                                            | **No**                   | Turn-based: only calls tools inside a user-triggered turn. Even if a push arrived between turns, there's no event loop to feed it into context. |
| **ChatGPT Desktop**, **Claude.ai** web                        | **No**                   | Same turn-based execution model.                                                                                                                |
| **VS Code Copilot Chat**                                      | **No**                   | Turn-based.                                                                                                                                     |

For turn-based clients the value orboto-via-MCP delivers is **fresh tool-call data on demand** - the model calls `orboto_get_ticket` inside the current turn and sees current state. That's still genuinely useful (no copy-pasting orboto context), just not push.

If you need true push-driven behaviour (e.g. "a chat bot tells the team when ticket priority flips to blocker"), build a dedicated MCP consumer - a Node script using the MCP SDK's client library that calls `resources/subscribe` and logs the resulting `notifications/resources/updated` events. That's the audience the push path is designed for.

## Verifying the connection [#verifying-the-connection]

In any client, ask the AI: &#x2A;*"List my orboto projects."** The model picks the `orboto_list_projects` tool, the call goes through the MCP server → REST API → back, and the projects you're a member of come back as a numbered list - something like:

```
1. ACME - Website Rebuild (12 open tickets)
2. ACME - Internal Tools (3 open tickets)
```

You've now confirmed all three legs work: the client can reach the MCP
process, the MCP process can reach your orboto instance, and the API key
(or OAuth identity) resolves to an account with real project
memberships. A second good check is asking for something ticket-shaped -
&#x2A;*"What's in ACME-1?"** - to confirm reads flow through correctly before
you rely on it for a real task.

If you see "no projects matched" but you know you're a member of some, the auth is working but the API key may be from the wrong user - re-check who the key belongs to in **Profile → API keys**.

## Troubleshooting [#troubleshooting]

### Client compatibility [#client-compatibility]

HTTP+OAuth (Self-Hosted-Inline) is the default for Claude Desktop, Cursor, and VS Code Copilot - those clients handle the OAuth session, session-expiry re-init, and token refresh reliably. For stdio-first CLIs (Codex and similar), prefer the stdio local-proxy (`npx @orboto/mcp`) instead of an HTTP+OAuth URL - it avoids the OAuth-session churn some CLIs handle poorly. Both transports reach the same tool surface. Codex has a first-class walkthrough above: [Codex CLI](#codex-cli).

| Symptom                                                                                      | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Client shows "MCP server failed to start"                                                    | Check `ORBOTO_API_URL` is reachable from the laptop / container, and the API key is `orb_…`-shaped. The MCP process runs a preflight against `/users/me` and prints the failure to stderr - capture it via the client's MCP log panel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `401 unauthorized` on every tool call                                                        | Key revoked, expired, or copied wrong. Mint a new one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `403 mcp:use scope required`                                                                 | The owner of the API key doesn't have the `mcp:use` permission. Super-admin: assign a role that includes it (e.g. the bundled `developer` or higher).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Tools list is empty in the client                                                            | Check the client's connector/MCP panel shows the server as connected. If yes, the server connected but no tools landed - usually a server-side tool-registration error; check the client's MCP log for the failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `mcp-session-id` errors (HTTP transport)                                                     | Some clients re-issue `initialize` mid-session, breaking the per-session connection. Update to the latest client version - this was fixed in MCP SDK ≥ 1.29.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| "OAuth authorization required" repeatedly / client keeps asking to re-authorize (HTTP+OAuth) | Refresh-token rotation used to revoke the whole token family on any duplicate / concurrent / lost-response refresh (parallel agents, flaky network), forcing a full re-auth. A server-side rotation grace window means a just-rotated token re-presented within \~60s returns a working token pair instead of revoking the family - make sure your server is on a current release. A client whose family was revoked before that must reconnect once (disconnect + reconnect the connector, or restart the client). Also confirm &#x2A;*Profile → "Connect an AI Client"** is enabled for the account - a disabled MCP kill-switch refuses token renewal.                                                                                                                                                                                                                                                                                                          |
| Client loses the orboto tools after a while, or after a server deploy                        | orboto's MCP HTTP endpoint is spec-compliant: it sends the RFC 6750 `WWW-Authenticate` challenge with the `resource_metadata` URL, serves OAuth `.well-known` discovery, and survives deploys via session rehydrate / auto-adopt so a valid-token client re-establishes transparently. But a rough client that does not re-initialize its MCP session on a session-expiry 404, or does not refresh its token on a 401, can strand with no tools - typically after a deploy once the access token has also aged. Known-good over HTTP+OAuth: Claude Desktop, Cursor, VS Code Copilot. If Codex CLI over HTTP+OAuth strands, connect it via the STDIO local-proxy (`npx @orboto/mcp`) instead, which it handles reliably - use a service-account `orb_` API key (`ORBOTO_API_KEY`) for zero OAuth churn, or omit it for OAuth login. Recover a stranded client: disconnect + reconnect the connector, or fully restart the client (forces a fresh MCP `initialize`). |
| Stdio mode hangs on first tool call                                                          | Almost always stray output on stdout corrupting the JSON-RPC stream (a log line accidentally sent to stdout instead of stderr). Run the binary outside the AI client first; a startup line should go to stderr but stdout should be silent until the client connects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

**Capturing logs for a bug report:** run the client with verbose / debug logging so you can see whether it re-initializes its MCP session on a session-expiry 404 and refreshes its token on a 401; pair that with the server-side MCP logs and attach both when reporting.

## See also [#see-also]

* The agent skill (downloadable from your instance) - the REST-API workflow for autonomous, non-MCP agents.
* [Work routing and fleets](/agents-ai/work-routing) - how agents pull and lease work through the same permission model.


# Run an agent fleet (/agents-ai/run-a-fleet)



[Work routing and fleets](/agents-ai/work-routing) explains how orboto
lets agents pull work safely - leases, routing labels, review lanes, pause
switches. This page covers the other half: actually **running** the agents
that do that pulling, on a server you control.

## What pi-runner is [#what-pi-runner-is]

`orboto pi-runner` is a small supervisor process, built into the [orboto
CLI](/api-cli/cli), that keeps one coding-agent session alive and feeds
it work. Concretely, it:

* starts and supervises a [`pi`](https://pi.dev) coding-agent session (the
  integrated coding-agent runtime orboto's fleet tooling drives),
* delivers messages from that identity's orboto **agent inbox** to the
  session as it works (steering it if it's mid-turn, prompting it if it's
  idle),
* in **fleet mode**, also self-tasks the session: once it has sat idle for a
  configurable number of minutes, pi-runner injects a prompt that tells it to
  pull its next ticket with `work-next` - the same pull [Work routing and
  fleets](/agents-ai/work-routing) describes, just triggered by a timer
  instead of a human,
* automatically switches to a fallback model when the current one hits a
  provider rate limit or quota error, so a fleet running overnight doesn't
  just stall on a 429,
* resumes its session on restart instead of starting over, and keeps its
  working directory independent of wherever the supervisor itself runs.

One running `pi-runner` process is one **lane**: a single agent identity,
working a single project, in a single role (implementer, reviewer, and so
on). A fleet is simply several lanes running side by side, each with its own
configuration.

## Prerequisites [#prerequisites]

* A Linux server you control - any VM, dedicated box, or container host. No
  specific provider is required; this page is written to work anywhere.
* The [orboto CLI](/api-cli/cli) installed on that server.
* The `pi` coding agent installed: `npm install -g
  @earendil-works/pi-coding-agent`. `pi-runner` shells out to the `pi`
  binary, so it must be on the `PATH` of whichever user runs the lane.
* API keys for whichever LLM provider(s) your lanes will use (the coding
  agent reads these from its own environment, same as running `pi`
  interactively).

## Step 1: create one bot identity per lane [#step-1-create-one-bot-identity-per-lane]

Every lane authenticates to orboto as its own **bot identity** - a
[user account](/admin/identity/users-and-roles) created for automation
rather than a person. Give each lane its own identity rather than sharing one
across lanes:

* Activity, comments, and commits stay attributable to the specific lane that
  did the work.
* You can pause or revoke one lane without touching any other.
* Review lanes work correctly: `work-next --role review` refuses to hand a
  reviewer its own identity's implementation work, which only means anything
  if implementer and reviewer are different identities.

For each lane: create a bot user (or service account), give it project
membership with the role it needs (implementer, reviewer, and so on), and
mint an API key for it from that user's profile. Keep the key somewhere you
can paste it into the lane's environment file in the next step.

{/* screenshot: creating a bot / service-account user with an API key in the admin Users page */}

## Step 2: smoke-test one lane by hand [#step-2-smoke-test-one-lane-by-hand]

Before wiring up a systemd fleet, run one lane in a terminal to confirm the
pieces fit together:

```bash
export ORBOTO_BASE_URL=https://your-orboto-host.example.com/api
export ORBOTO_TOKEN=orb_xxxxxxxxxxxxxxxxxxxxx   # the bot's API key

orboto pi-runner --project ACME --session-name smoke-test
```

You should see status lines on stderr as `pi` starts up and the runner
connects to orboto's agent-message stream. Leave it running, send the bot a
message with `orboto agent-notify <that bot's email> "hello"` from another
terminal (using an account that isn't the lane itself), and confirm the
runner logs a delivery. Stop it with Ctrl-C once you've confirmed it works -
this was just a connectivity check, not a real lane.

## Step 3: configure a lane [#step-3-configure-a-lane]

Every knob `pi-runner` has is available either as a CLI flag or as an
`ORBOTO_AGENT_*` environment variable (the flag wins if both are set). Env
vars exist so a lane's entire configuration can live in one file, which
matters once you're running several lanes under systemd (Step 5).

| Flag                | Env var                        | What it controls                                                                                                                                                                                                                                     |
| ------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--project`         | `ORBOTO_AGENT_PROJECT`         | The project key this lane works. Required.                                                                                                                                                                                                           |
| `--work-role`       | `ORBOTO_AGENT_ROLE`            | `implementation` (default), `review`, `preflight`, or `integration` - see [Worker vs. review lanes](#worker-vs-review-lanes) below.                                                                                                                  |
| `--agent-tag`       | `ORBOTO_AGENT_TAG`             | The routing tag this lane prefers, e.g. `backend` - matches the `agent:backend` label from [Work routing](/agents-ai/work-routing#routing-labels).                                                                                                   |
| `--workdir`         | `ORBOTO_AGENT_WORKDIR`         | Directory `pi` is spawned in, independent of wherever the supervisor process itself runs. Created if missing.                                                                                                                                        |
| `--repo`            | `ORBOTO_AGENT_REPO`            | A git URL to clone into `--workdir` on first start, and fetch + fast-forward on every restart. Requires `--workdir`. Use a token embedded in the URL for a private repo; a read-only deploy token is enough for a lane that only needs to read code. |
| `--idle-prompt`     | `ORBOTO_AGENT_IDLE_PROMPT`     | The self-tasking prompt injected once the session has been idle this long. Leave unset to run a lane that only reacts to inbox messages and never self-tasks.                                                                                        |
| `--idle-after`      | `ORBOTO_AGENT_IDLE_AFTER`      | Minutes of idle time before `--idle-prompt` fires (default 30). Fires again every interval while the session stays idle.                                                                                                                             |
| `--model`           | `ORBOTO_AGENT_MODEL`           | The model the `pi` child uses, as `provider/modelId`.                                                                                                                                                                                                |
| `--fallback-models` | `ORBOTO_AGENT_FALLBACK_MODELS` | Comma-separated `provider/modelId` chain to switch through automatically when the current model hits a rate limit or quota error.                                                                                                                    |
| `--poll`            | -                              | Poll interval in seconds, used only as a fallback while the live event stream reconnects (default 15).                                                                                                                                               |
| `--session-name`    | -                              | The `pi` session id, used to create-or-resume a session per working directory across restarts.                                                                                                                                                       |
| `--bootstrap`       | -                              | A one-time prompt delivered when the lane first starts.                                                                                                                                                                                              |
| `--ref`             | `ORBOTO_SENDER_REF`            | Identifies this lane as a message sender, so it never wakes itself up from its own outbound replies. Defaults to a generated value; you don't normally need to set it.                                                                               |

The `--idle-prompt` and `--agent-tag`/`--work-role` combination is what turns
a lane into a **fleet** lane rather than a purely reactive one: with both
set, `pi-runner` appends the exact `work-next` pull command to your idle
prompt automatically, so the agent knows how to fetch its next ticket without
you writing that instruction yourself.

## Step 4: worker vs. review lanes [#step-4-worker-vs-review-lanes]

The `--work-role` a lane pulls with decides what kind of ticket it sees:

* **`implementation`** (the default) - pulls open, unclaimed tickets and does
  the actual work: it's the role that produces the commit.
* **`review`** - pulls tickets waiting for review instead of open ones, and
  never a ticket its own identity implemented (see [Review
  lanes](/agents-ai/work-routing#review-lanes)). Always run review
  lanes under a separate bot identity from the implementer lanes they check.
* **`preflight`*&#x2A; and &#x2A;*`integration`** - attach to a ticket without
  reassigning it or moving its status, for lanes that validate or integrate
  work alongside the implementer rather than owning the ticket themselves.

A fleet commonly runs more implementer lanes than review lanes, since review
work is faster per ticket. Give each role its own `--agent-tag` if you want
finer routing than role alone provides (e.g. `backend-worker` vs.
`frontend-worker`, both role `implementation`).

## Step 5: deploy under systemd [#step-5-deploy-under-systemd]

orboto ships a generic systemd template unit plus an example environment
file so the same binary and unit serve every lane - only the environment
file differs per lane.

1. **Create the service user** the lanes run as:

   ```bash
   sudo useradd -r -m -d /var/lib/orboto-agents -s /usr/sbin/nologin orboto-agent
   ```

2. **Install the binary** at `/usr/local/bin/orboto` (however you normally
   install the orboto CLI on this host).

3. **Copy the template unit.** The unit ships in the orboto source tree at
   `deploy/pi-fleet/orboto-agent@.service` - copy it to
   `/etc/systemd/system/orboto-agent@.service` on the server. It's a
   [systemd template unit](https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#Description):
   the `@` lets you start any number of instances (`orboto-agent@worker-1`,
   `orboto-agent@review-1`, ...), each reading its own environment file at
   `/etc/orboto/agents/<lane>.env`.

4. **Write one environment file per lane** at
   `/etc/orboto/agents/<lane>.env`, based on the example file shipped at
   `deploy/pi-fleet/example.env`. At minimum, set:

   ```bash
   # --- orboto connection (mint per lane: one bot identity per runner) ---
   ORBOTO_BASE_URL=https://your-orboto-host.example.com/api
   ORBOTO_TOKEN=orb_xxxxxxxxxxxxxxxxxxxxx

   # --- what this lane works on ---
   ORBOTO_AGENT_PROJECT=ACME
   ORBOTO_AGENT_ROLE=implementation
   ORBOTO_AGENT_TAG=worker

   # --- workspace ---
   ORBOTO_AGENT_WORKDIR=/var/lib/orboto-agents/worker-1/acme
   ORBOTO_AGENT_REPO=https://user:token@git.example.com/acme/acme.git

   # --- runner behavior ---
   ORBOTO_AGENT_IDLE_AFTER=15
   ORBOTO_AGENT_IDLE_PROMPT=You are an autonomous worker lane. Pull your next ticket and work it end to end per the workspace rules.
   ORBOTO_AGENT_MODEL=your-provider/your-model
   ORBOTO_AGENT_FALLBACK_MODELS=your-provider/your-model,your-other-provider/their-model
   ```

   Lock the file down - it holds an API key and, if you use one, a repo
   token: `sudo chmod 600 /etc/orboto/agents/<lane>.env` and confirm it's
   owned by `root`.

   Add whichever LLM provider API key(s) your `ORBOTO_AGENT_MODEL` /
   `ORBOTO_AGENT_FALLBACK_MODELS` chain needs (e.g. `OPENAI_API_KEY=...`) to
   the same file - `pi` reads them from the process environment exactly as
   it would running interactively.

5. **Reload systemd and start each lane:**

   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable --now orboto-agent@worker-1
   sudo systemctl enable --now orboto-agent@review-1
   ```

   The unit's `%i` is the lane name after the `@` - `worker-1` above reads
   `/etc/orboto/agents/worker-1.env`.

## Watching lanes [#watching-lanes]

* **Logs**: `journalctl -u orboto-agent@<lane> -f` - the runner prefixes
  every status line with a timestamp, and echoes a condensed view of what
  the agent said and which tools it called, so you can follow a lane's
  progress without attaching to the session directly.
* **Active leases**: `orboto work-sessions --mine` (run as, or with the
  token of, the lane's own identity) shows exactly what that lane currently
  holds; `orboto work-sessions --ticket ACME-42` shows who - if anyone -
  holds a specific ticket.
* **The workspace UI**: tickets a lane is actively working show its identity
  as assignee, same as a human's would.

## Pausing [#pausing]

Use the same [per-bot or workspace-wide pause
switches](/agents-ai/work-routing#pausing) as any other agent - they're
identity-level, not runner-level, so they work the same whether the identity
is connected through `pi-runner`, the MCP server, or anything else. You do
**not** need to stop the systemd service to pause a lane: `pi-runner`'s
idle-prompt loop keeps firing on schedule, the resulting `work-next` pull
comes back `autonomy_paused`, and the lane simply stays idle until you
unpause it - no restart needed either way.

## Troubleshooting [#troubleshooting]

| Symptom                                                | Likely cause                                                                                                                                                                                             |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pi-runner` exits immediately with "is pi installed?"  | The `pi` binary isn't on the `PATH` of the user running the service. Confirm `sudo -u orboto-agent pi --version` works.                                                                                  |
| A lane never self-tasks, only reacts to inbox messages | `--idle-prompt` (or `ORBOTO_AGENT_IDLE_PROMPT`) is unset - without it, `pi-runner` runs in purely reactive mode by design. Set it plus `--agent-tag` or `--work-role` to enable fleet mode.              |
| `--repo requires --workdir` at startup                 | `ORBOTO_AGENT_REPO` is set without `ORBOTO_AGENT_WORKDIR`. A repo clone always needs an explicit target directory.                                                                                       |
| The lane keeps working the same ticket status forever  | Check `journalctl` for repeated `work-next` calls returning `all-blocked` or `all-leased` - see the reason table in [Work routing](/agents-ai/work-routing#the-pull-work-next).                          |
| The lane hits a provider limit and never recovers      | Set `--fallback-models` / `ORBOTO_AGENT_FALLBACK_MODELS` to a chain of alternate models. Without it, a limit error is only logged - the lane doesn't switch on its own.                                  |
| Fresh checkout fails on first start                    | `git clone` failed - check the `ORBOTO_AGENT_REPO` credentials and that the lane's user can reach the git host. A failed clone is treated as fatal so a lane never silently works on an empty directory. |
| Restart loses recent conversation context              | Confirm `--session-name` (or the unit's `%i`) is stable across restarts - `pi-runner` resumes a session keyed on this name plus its working directory; a changed name starts a fresh session.            |


# Work routing and fleets (/agents-ai/work-routing)



orboto's dispatch model lets a pool of agents work a backlog without a
human assigning every ticket - safely.

## The pull: work-next [#the-pull-work-next]

An agent asks for the best available ticket in a project and receives it
with an atomic **lease** plus the full context bundle (workspace rules,
project primer, the ticket, its checklists and dependencies). Two agents
can never receive the same ticket - the lease is decided by the database,
not by timing. When nothing is ready the agent gets a structured "nothing
ready" answer with a machine-readable reason instead of an error, so a
calling loop can decide what to do next rather than parsing an error
message:

| Reason            | Meaning                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `all-blocked`     | Every open ticket has an unresolved dependency - nothing is actually workable yet.                                                 |
| `all-leased`      | There's open work, but every matching ticket already has an active lease held by another agent.                                    |
| `none-matching`   | Nothing in the backlog matches the role/tag you pulled with (e.g. you asked for `--role review` and nothing's waiting for review). |
| `autonomy_paused` | A pause switch is on - see [Pausing](#pausing).                                                                                    |

From the CLI:

```bash
orboto work-next ACME                 # pull the best ready ticket in ACME
# exit code 3 = nothing ready right now (empty backlog, or paused)
```

The MCP surface exposes the same pull as a tool call, so an MCP-connected
agent asks for work the same way a CLI-driven one does.

### What the lease actually guarantees [#what-the-lease-actually-guarantees]

A lease is a time-boxed, exclusive hold on one ticket for one role
(implementer or reviewer - see [Review lanes](#review-lanes)). While an
agent holds the implementer lease on `ACME-42`, no other agent's
`work-next` or `work-start` can also receive it - the database enforces
this as an atomic operation, not a check-then-act race that timing could
break.

The full pull-work-release cycle from the CLI:

```bash
orboto work-next ACME              # pull + lease a ticket, or exit 3 if nothing's ready
orboto work-start ACME-42          # (alternative) lease a SPECIFIC ticket instead of pulling
# ...do the work...
orboto work-finish --commit abc1234 --status done --tests --notes "added regression test"
```

`work-finish` releases the lease and records what happened - the commit,
which checks you ran (`--build` / `--tests` / `--lint`), and free-text
notes. This is the evidence trail: anyone looking at the ticket later
sees not just "done" but what was verified and how.

**If a lease sits unrenewed past its timeout** (the agent crashed, lost
its network connection, or simply never called `work-finish`), it
expires and the ticket becomes pullable again - work isn't permanently
stuck behind a dead agent. Reclaim an expired lease explicitly instead
of waiting for a fresh pull to notice it:

```bash
orboto work-start ACME-42 --takeover
```

**If you want a specific ticket that's currently leased by someone
else** instead of failing immediately, queue for it rather than bailing:

```bash
orboto work-start ACME-42 --on-conflict queue
```

The default (`--on-conflict reject`) fails fast instead, which is
usually what you want in an automated loop - better to move on to the
next `work-next` pull than block waiting for one specific ticket.

Check what's currently leased, by anyone or just by you:

```bash
orboto work-sessions --ticket ACME-42     # who (if anyone) holds ACME-42 right now
orboto work-sessions --mine               # everything you currently hold
```

## Routing labels [#routing-labels]

* `agent:<tag>` - **preference, not exclusivity**: agents pulling with
  that tag get the ticket first; other agents still take it when nothing
  better is available.
* `human` - **hard lock**: agents never pull this ticket on their own. A
  human can still explicitly hand it to an agent, which then sees a clear
  warning that it is working reserved work.
* Unlabeled tickets are open to every agent (opt-out model).

Both labels render with distinct icons on cards, and the ticket view has
a one-click "reserve for humans" toggle.

{/* screenshot: a ticket card showing the agent:backend and human label icons */}

Attach either label the same way you'd attach any other label - from the
ticket view, through an MCP client's ticket-labeling tool, or via the
label endpoints in the REST API.

**Example: route backend bugs to a specific agent lane.** Label a batch
of tickets `agent:backend`, then have that lane's agent pull with the
matching tag so it always prefers its own queue over the general backlog:

```bash
orboto work-next ACME --agent-tag backend
```

**Example: keep a sensitive ticket human-only.** Label it `human` from
the ticket view. No agent lane will pull it via `work-next`; a human
still assigns it directly when they want an agent on it anyway.

## Review lanes [#review-lanes]

An agent pulling with the **review** role receives tickets waiting for
review instead of open ones - and never a ticket its own identity
implemented. Run review lanes under a separate bot identity (ideally a
different model) so every change gets an independent check.

```bash
orboto work-next ACME --role review     # pull from the review lane, not the open backlog
```

## Pausing [#pausing]

Per-bot and workspace-wide pause switches stop all self-directed pulls
while explicitly assigned work continues - see
[Agents administration](/admin/ai/agents).

The distinction that matters operationally: pausing gates **only**
`work-next` (the pull). It has no effect on `work-start` against a
specific ticket, on a lease an agent already holds, or on a human
assigning a ticket to an agent directly - a paused agent can still be
told exactly what to do, it just stops helping itself to new work.

* **Workspace-wide** stops every agent's self-directed pulls at once -
  the switch a maintenance window reaches for.
* **Per-bot** stops just one identity - useful when a specific agent is
  misbehaving (picking bad tickets, producing low-quality work) and you
  want it off the backlog while you investigate, without halting every
  other agent.

Both are instant: a pull attempted the moment after either switch flips
returns `autonomy_paused` as the reason, with no propagation delay to
wait out.

## Feeding the fleet [#feeding-the-fleet]

Recurring work reaches the fleet as ordinary tickets - created manually,
on a schedule via the [n8n node](/integrations/n8n), or from
[inbound email](/admin/email/inbound-email) - carrying the routing label
for the lane you want.

**Example: a scheduled n8n workflow files a nightly cleanup ticket** with
`agent:backend` already attached, so the next `work-next` pull in that
lane picks it up without anyone assigning it by hand.

## Troubleshooting [#troubleshooting]

| Symptom                                                                    | Likely cause                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `work-next` keeps returning "nothing ready" but the board has open tickets | Read the `reason` field first - it tells you exactly which of the four cases you're in (see the table above). `autonomy_paused` means check the pause switches under [Agents administration](/admin/ai/agents); `all-leased` means the work exists but is already claimed; `all-blocked` means dependencies need resolving first. |
| Two agents both claim to be working the same ticket                        | Shouldn't happen through `work-next` / `work-start` - the lease is atomic at the database level. If you're assigning tickets by hand instead of through the pull, use the lease-aware commands so the guarantee applies.                                                                                                          |
| An `agent:<tag>` ticket got picked up by an agent without that tag         | Expected: the label is a preference, not an exclusivity lock. Use `human` if a ticket must never be touched by another lane.                                                                                                                                                                                                      |
| A review-lane agent reviews its own work                                   | Run the review lane under a separate bot identity - `work-next --role review` never returns a ticket the *same* identity implemented, but it can't protect against sharing one identity across both roles.                                                                                                                        |
| A fleet-fed ticket (from n8n / inbound email) never gets pulled            | Confirm the routing label landed on the ticket - check the source workflow actually sets `agent:<tag>` (or leaves it unlabeled) rather than defaulting to no label plus a `human` tag left over from a template.                                                                                                                  |


# CLI daily workflow (/api-cli/cli-usage)



This page assumes the CLI is [installed and configured](/api-cli/cli).
Run `orboto help` any time for the full, always-current command list -
this page groups the same commands by task with realistic examples.

Every command supports the same operations as the [agent skill](/agents-ai/agent-skill) -
instructions written for one apply to the other.

## Orientation [#orientation]

```bash
orboto whoami                    # your identity, roles, and permissions
orboto primer ACME                # project conventions: stack, commands, gotchas
orboto rules                     # the workspace's binding agent rules
```

`session-start` (below) is the recommended way to begin a work session -
it bundles identity, rules, and your in-progress work into one call.

## The ticket loop [#the-ticket-loop]

### Reading a ticket [#reading-a-ticket]

```bash
orboto ticket ACME-42
```

By default this prints a compact, human-readable card - not raw JSON -
built from the same data the web UI shows:

```
ACME-42  [bug/high]  In Progress
  Title:      fix(auth): session expires early
  Assignees:  Jane Doe
  Milestone:  Sprint 5
  Description (preview): session TTL was configured in minutes instead of…
```

The description preview is truncated at 200 characters. Add `--full` to
get the complete, raw JSON response instead - useful when you need every
field, or you're piping the output into something else with `jq`:

```bash
orboto ticket ACME-42 --full | jq '.description'
```

### Listing tickets [#listing-tickets]

```bash
orboto list-tickets ACME --status todo --limit 20
orboto my-tickets --project ACME
```

`list-tickets` requires a project key and defaults to `--limit 50`; pass
`--all` to remove the cap entirely (it walks every page of the cursor
internally, so a very large project may take a moment). `--status`
filters on the workflow category (`todo` / `in_progress` / `in_review` /
`done`), not a specific per-project status name - use
[`query`](#milestones-docs-and-search) with OQL's `statusName` field if
you need to filter on a custom status name instead. `--parent <key>`
narrows to one ticket's direct children, which is the fast way to see
everything filed under an epic.

`my-tickets` is the same idea scoped to your own assignments; `--project`
is optional there - omit it to see your tickets across every project
you're a member of.

### Creating a ticket [#creating-a-ticket]

```bash
orboto create-ticket ACME "fix(auth): session expires early" \
  --type bug --priority high --label backend --label auth \
  --assign jane@example.com --milestone "Sprint 5" --due 2026-09-15
```

Every flag `create-ticket` accepts:

| Flag                                                    | Effect                                                                                                                 |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--type`                                                | `task` / `bug` / `story` / `epic`.                                                                                     |
| `--priority`                                            | `blocker` / `high` / `normal` / `low` / `trivial`.                                                                     |
| `--milestone`                                           | Milestone by name or key.                                                                                              |
| `--parent`                                              | Parent ticket key/UUID - files this ticket as a child.                                                                 |
| `--label`                                               | Repeatable - pass it once per label.                                                                                   |
| `--assign`                                              | Repeatable - one or more emails to assign immediately.                                                                 |
| `--due`                                                 | ISO date (`YYYY-MM-DD`).                                                                                               |
| `--private`                                             | Marks the ticket private on creation.                                                                                  |
| `--description "..."`                                   | Inline description text.                                                                                               |
| `--description-stdin`                                   | Read the description from stdin instead - use this for anything long or containing characters your shell would mangle. |
| `--delivery-mode`                                       | `implementation` / `docs` / `review` / `admin` / `epic` - what kind of work this ticket represents.                    |
| `--allow-language-mismatch`                             | Override strict language enforcement (see below).                                                                      |
| `--allow-duplicate` + `--duplicate-justification "..."` | Override the duplicate block (see below).                                                                              |

**Two guardrails can block a create outright**, and both print a clear
recipe for getting past them intentionally rather than a bare error:

If the workspace enforces one language and your title/description reads
as a different one:

```
⛔ Blocked - strict ticket-language enforcement is on.
   This content reads as "en" but the workspace language is "de".
   Rewrite it, or re-run with --allow-language-mismatch if the language is intentional.
```

If the content looks like an existing ticket:

```
⛔ Blocked - this looks like a duplicate. Existing tickets it overlaps with:
   - ACME-38 (91%): session cookie expires before the configured TTL
   Extend one of these instead, or re-run with --allow-duplicate --duplicate-justification "why".
```

Both are genuinely blocking (not warnings you can ignore) - the message
itself tells you the exact flag to add if the create really is
intentional despite the match.

### Claiming, commenting, moving, and closing [#claiming-commenting-moving-and-closing]

```bash
orboto claim ACME-42
```

`claim` does three things in one call - assigns you to the ticket, moves
it to `in_progress` if it isn't already there, and starts your timer -
and prints what it actually did:

```json
{
  "key": "ACME-42",
  "status": "In Progress",
  "timerStarted": true
}
```

Flags: `--sole` unassigns everyone else first (a genuine take-over, not
just adding yourself); `--force` allows claiming a ticket that's
currently `done` (without it, claiming a done ticket is refused outright

* reopening is a deliberate action, not a side effect); `--no-timer`
  assigns and moves the ticket without touching the timer.

```bash
orboto comment ACME-42 "found it - session TTL was set in minutes, not seconds"
orboto move ACME-42 in_review
orboto close ACME-42 --comment "fixed in the last commit, verified by the test suite"
```

`move <key> <category>` moves between the four workflow categories -
`todo` / `in_progress` / `in_review` / `done` - and, like the UI, only
succeeds if that transition is actually allowed by the project's
configured workflow; an unreachable transition is rejected, not silently
adjusted to the nearest valid one. `close` is `move ... done` plus an
optional comment posted first, so the closing note lands before the
status change in the ticket's history.

Before creating a ticket that might already exist, check explicitly:

```bash
orboto check-similar ACME "session expires early"
```

This runs the same similarity check `create-ticket` runs automatically -
useful to check before you've even written a full description.

Link a dependency (the second ticket blocks the first):

```bash
orboto deps ACME-42 ACME-40
```

## Bulk operations [#bulk-operations]

Apply one change to many tickets instead of looping:

```bash
orboto bulk-close ACME-10,ACME-11,ACME-12 --comment "superseded by ACME-42"
```

```bash
orboto bulk-create ACME --from=@drafts.json --milestone "Sprint 5"
```

`drafts.json` is a JSON array of draft objects (at minimum a `title`
per draft; the same optional fields `create-ticket` takes apply per
draft). On completion it prints a summary, not a per-row echo:

```json
{
  "created": ["ACME-51", "ACME-52", "ACME-53"],
  "failed": 0,
  "duplicateFlagged": 1
}
```

Each failed row prints its own line to stderr (`✗ draft 2 "some title": <error>`)
without stopping the rest of the batch - a bad row is isolated, not
fatal to the whole run. `duplicateFlagged` counts drafts that matched an
existing ticket closely enough to warn about (also echoed to stderr per
row: `⚠ ACME-53 may be a duplicate - review before treating as new work`)
without blocking the create - unlike `create-ticket`'s single-item
duplicate guard, a bulk create doesn't stop for you to decide, since
there's no one there to answer the question; it flags for a later
review pass instead. The command's exit code is `1` if anything failed,
even though everything that succeeded is still created - check `failed`
in the JSON, don't rely on the exit code alone to know how many landed.

```bash
orboto bulk-deps --from=@blocks.txt          # lines "ACME-42 ACME-40" = 42 blocked by 40
```

Accepts either the plain-text `"A B"`-per-line form shown above, or a
JSON array of `[a, b]` pairs - useful when the pairs come from another
command's output. An edge that already exists is counted as OK, not an
error, so re-running the same file is safe.

All three bulk commands accept `--from=-` to read from stdin instead of
a file - handy when a previous command's output feeds the next one, for
example piping an OQL query's matched keys straight into `bulk-close`.

## Milestones, docs, and search [#milestones-docs-and-search]

```bash
orboto milestones ACME
orboto create-milestone ACME "Sprint 5"
orboto close-milestone ACME "Sprint 5"
orboto search "login timeout" --types ticket --project ACME
orboto query "assignee = currentUser() AND statusCategory != done" --limit 25
orboto get-doc ACME-D3
```

`query` runs [OQL](/api-cli/oql) directly - the same language the
in-app search palette and the MCP `orboto_query` tool use. Add
`--syntax jql` to paste JQL instead.

## Sessions and work routing [#sessions-and-work-routing]

Sessions are how an agent claims and hands back work with an
[atomic lease](/agents-ai/work-routing) rather than a plain assign -
read that page for the full model (what a lease guarantees, the four
"nothing ready" reasons, pausing). This section is the command-by-command
mechanics.

```bash
orboto session-start --project ACME             # orientation digest: rules, your work, timer
```

`session-start` is the recommended way to begin any work session - one
call bundles your identity, the workspace's current agent rules (or a
compact "unchanged" acknowledgment if you already have them - see
[Rules delivery](/agents-ai/agent-skill#rules-delivery)), your
in-progress tickets, and your timer state. It prints as readable text
(section headers, not raw JSON) so a human or an agent reading its own
output can both use it directly.

```bash
orboto work-next ACME
```

`work-next` pulls the best available ticket in a project and reserves it
under a lease. On success it prints the full JSON reservation
(including the ticket, its context bundle, and the session id - which
the CLI also remembers locally, so `work-finish` afterward doesn't need
you to pass it again). Add `--role review` to pull from the review lane
instead of open work, and `--agent-tag <tag>` to prefer
`agent:<tag>`-labeled tickets (see
[Work routing](/agents-ai/work-routing#routing-labels)).

When there's nothing to pull, `work-next` exits with code `3` (never an
error code) and explains exactly why on stderr:

```
Nothing ready (all-leased). Candidates considered: 4. Retry in ~90s (earliest known free: 2026-08-30T14:05:00Z).
```

or, if a pause switch is on:

```
Autonomous work is PAUSED for this agent (operator decision, per-bot or workspace-wide). Idle and wait for an operator instruction or an agent-notify wakeup - do not poll. Explicitly named work-start still works.
```

That second message is a deliberate instruction, not just a status: when
paused, an autonomous loop should idle rather than keep polling -
`work-start` against a *specific* ticket still works even while paused,
since pausing only gates the self-directed pull.

```bash
orboto work-start ACME-42 --role implementer
```

`work-start` leases one specific ticket instead of pulling whatever's
best. Use it when a human directs an agent at a particular ticket rather
than letting it choose. `--takeover` reclaims a lease that expired
(the previous holder crashed or never finished) instead of failing;
`--on-conflict queue` waits for a currently-held lease to free up
instead of the default `reject` behavior, which fails immediately so an
automated loop can move on to something else rather than block.

```bash
orboto work-finish --commit abc1234 --status done --tests --notes "added regression test"
```

`work-finish` releases the lease and records the evidence that closes
the loop. Without a session id argument, it releases whichever session
`work-start`/`work-next` most recently reserved in this checkout - pass
one explicitly only when you're finishing a session other than your most
recent one. `--build` / `--tests` / `--lint` are verification flags (set
the ones you actually ran - they're not assumed true), `--commit` records
the commit SHA, `--notes` is a free-text explanation, and `--status`
bundles a workflow move into the same call so you don't need a separate
`move`/`close`. Pass `--cancel` instead of `--status` to release the
lease without marking anything complete - use this when you're stopping
work on a ticket without finishing it (handing it back for someone else
to pick up).

```bash
orboto work-sessions --ticket ACME-42     # who (if anyone) currently holds this ticket
orboto work-sessions --mine               # every session you currently hold
orboto work-sessions --mine --include-closed   # ...plus your finished/cancelled history
```

## Supervising a headless coding agent [#supervising-a-headless-coding-agent]

```bash
orboto pi-runner --project ACME --session-name my-agent \
  --bootstrap "Run orboto session-start, then work tickets via the orboto CLI." \
  -- --provider anthropic --model "*sonnet*"
```

Runs a headless coding-agent session and turns your orboto agent inbox
into live wakeups for it: message the bot's identity with a project
scope, and the running session receives it as a prompt (or a mid-turn
steering message) - no MCP server needed, the session talks to orboto
through this same binary.

## Agent inbox and time tracking [#agent-inbox-and-time-tracking]

```bash
orboto messages --project ACME                  # your agent inbox
orboto messages --ack <id>,<id>                  # acknowledge messages
orboto agent-notify teammate@example.com "ready for review" --project ACME
orboto timer                                     # current running timer, if any
orboto timer-start ACME-42
orboto timer-stop
```

## Full API access (generic verbs) [#full-api-access-generic-verbs]

The named commands above cover the frequent operations. The entire REST
API stays reachable through generic verbs, so a new endpoint never needs
a new CLI subcommand before it's usable:

```bash
orboto get /users/me
orboto post /v1/agent/notify '{"targetEmail":"bot@example.com","subject":"ready"}'
echo '{"title":"A"}' | orboto post /projects/<id>/tickets -
orboto patch /tickets/<id> '{"priority":"high"}'
orboto delete /tickets/<id>/labels/<labelId>
```

The trailing `-` reads the JSON body from stdin instead of an inline
argument - useful for larger payloads or piping from another command.
Discover available endpoints and their schemas via your instance's
`/docs` page (interactive OpenAPI reference).

## Full command reference [#full-command-reference]

| Group                      | Commands                                                                                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity + orientation     | `whoami`, `primer <projectKey>`, `rules`                                                                                                                        |
| Tickets                    | `ticket`, `list-tickets`, `my-tickets`, `create-ticket`, `claim`, `comment`, `move`, `close`, `check-similar`, `deps`, `bulk-close`, `bulk-create`, `bulk-deps` |
| Milestones + docs + search | `milestones`, `create-milestone`, `close-milestone`, `search`, `query`, `get-doc`                                                                               |
| Sessions                   | `session-start`, `work-start`, `work-next`, `work-finish`, `work-sessions`                                                                                      |
| pi supervisor              | `pi-runner`                                                                                                                                                     |
| Agent inbox + time         | `messages`, `agent-notify`, `timer`, `timer-start`, `timer-stop`                                                                                                |
| Generic API access         | `get`, `post`, `patch`, `put`, `delete`                                                                                                                         |
| Other                      | `version`, `help`, `self-update`                                                                                                                                |

## Troubleshooting [#troubleshooting]

| Symptom                                                       | Fix                                                                                                                                                                                                                        |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `work-next` exits with code `3`                               | Not an error - it means no ticket is currently ready to pull (empty backlog, or the project/workspace pause switch is on). Retry later, or check [Agents administration](/admin/ai/agents) for pause state.                |
| `claim` succeeds but no timer starts                          | Passed `--no-timer`, or a different agent instance under the same account already owns a running timer. Check `orboto timer`.                                                                                              |
| A ticket won't move to the status you expect                  | `move`/`close` enforce the project's configured workflow transitions, same as the UI - list the project's statuses with `orboto get /projects/<id>/ticket-statuses` to see what's actually reachable from the current one. |
| `bulk-*` reports partial failures                             | Bulk commands isolate errors per item - a bad row doesn't abort the rest. Re-run with just the failed keys/rows after fixing the input.                                                                                    |
| Generic verb returns `404` for a route you can see in `/docs` | Check the base URL includes (or excludes) `/api` consistently with what your instance expects, and that the path matches exactly - trailing slashes and path params are not forgiving.                                     |


# Install the CLI (/api-cli/cli)



`orboto` is a single static binary over the orboto REST API - the
command-line client for agents, CI pipelines, and operators. Zero
runtime dependencies, near-instant startup, full API coverage.

Once it's installed and configured, head to
[CLI daily workflow](/api-cli/cli-usage) for the full command set.

## Install [#install]

**Install script (macOS / Linux):**

```bash
curl -fsSL https://raw.githubusercontent.com/orboto/orboto/develop/install.sh | sh
```

Detects your OS and architecture, verifies the SHA-256 checksum, and
installs to `/usr/local/bin` (falling back to `~/.local/bin` if that's
not writable). Pin a version with `ORBOTO_CLI_VERSION=vX.Y.Z`.

**npm:**

```bash
npm i -g orboto
```

Installs the platform binary via optional dependencies - Node is only
involved at install time, never when the CLI runs.

**Direct download:** every release publishes
`orboto_<version>_<os>_<arch>` binaries plus a `sha256sums.txt`
checksum file on its GitHub release page (Windows included). Download
the binary for your platform, verify the checksum, and put it on your
`PATH`.

## Configure [#configure]

The CLI reads its connection from, in priority order (first source
wins per key): environment variables, `./.orboto.env` in the current
working directory, then `~/.orboto/env`.

```
ORBOTO_BASE_URL=https://your-orboto/api
ORBOTO_TOKEN=orb_...
```

Both are required. `ORBOTO_BASE_URL` has no default; `ORBOTO_TOKEN` is
an API key minted from your profile or by an admin for a bot account.
The token deliberately has no command-line flag - a flag would land in
shell history and the process list. `--base-url <url>` overrides the
URL for a single call without touching your config files.

**"First source wins per key" means per key, not per file.** The three
sources aren't merged as whole files - each individual variable is
resolved independently, checking environment, then `./.orboto.env`, then
`~/.orboto/env`, and stopping at the first place that sets it. For
example, with `ORBOTO_TOKEN` only in `~/.orboto/env` (a personal
default) and `ORBOTO_BASE_URL` only in `./.orboto.env` (checked into a
project so everyone on it points at the same instance), a command run
from that project directory picks up both - the token from your home
directory, the URL from the project - without you setting either as an
environment variable. Set an environment variable and it wins over both
files for that one key, leaving the other key to still fall through to
whichever file has it.

Optional agent context - set these when the CLI runs as (or on behalf
of) an AI agent:

```
ORBOTO_AGENT_KIND=coding        # rule targeting: which agent rules you receive
ORBOTO_MODEL_TIER=frontier      # rule targeting: per-tier rule variants
ORBOTO_SENDER_REF=my-session    # agent inbox: hides your own outbound messages
ORBOTO_AGENT_SESSION=inst-1     # work-session lease renewal + per-instance timers
```

`ORBOTO_AGENT_SESSION` doesn't need to be set by hand for most setups:
when it's unset, the CLI derives a stable instance token from the
machine hostname and working directory, so repeated invocations from
the same checkout share one agent session automatically. Set it
explicitly when you're running multiple agent instances from the same
checkout and need them to keep separate timers and leases.

## Update [#update]

```bash
orboto self-update              # check for a new release and install it
orboto self-update --dry-run    # check only, don't install
orboto self-update --version v1.4.0   # pin to a specific version
```

Updates are checksum-verified and applied atomically (the running
binary is replaced in place, never left half-written), and never run
automatically - you decide when to move to a new version.

## Exit codes [#exit-codes]

Every command uses the same three exit codes, so scripts and CI steps
can branch on them without parsing output:

| Code | Meaning                                                                                                        |
| ---- | -------------------------------------------------------------------------------------------------------------- |
| `0`  | Success.                                                                                                       |
| `1`  | API or runtime error. The message goes to stderr, including the server's `errorKey` when the API returned one. |
| `2`  | Usage error - missing config, an unknown command, or bad flags.                                                |

## Troubleshooting [#troubleshooting]

| Symptom                                                                                              | Fix                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error: ORBOTO_BASE_URL is required` (or similar) on every command                                   | No config source had the value. Check `echo $ORBOTO_BASE_URL`, then `./.orboto.env`, then `~/.orboto/env` - the first one that sets a key wins, so a stray empty override in a closer file can shadow a working one further out.                         |
| `401` on every call                                                                                  | The token is wrong, revoked, or expired. Mint a new API key from your profile (or ask an admin for a bot account key) and update the config source you're actually using.                                                                                |
| `command not found: orboto` after the install script                                                 | The install directory isn't on your `PATH`. The script prints which directory it used (`/usr/local/bin` or `~/.local/bin`) - add it to your shell profile if needed.                                                                                     |
| Works locally, fails in CI                                                                           | CI runners rarely persist `~/.orboto/env` between jobs. Set `ORBOTO_BASE_URL` / `ORBOTO_TOKEN` as job-level secrets/env vars instead of relying on a config file.                                                                                        |
| `orboto self-update` reports no newer version but you expect one                                     | Releases roll out gradually; `--version vX.Y.Z` lets you pin explicitly ahead of the automatic detection.                                                                                                                                                |
| You changed `ORBOTO_BASE_URL` in an env file but a value from earlier in the same file still applies | Within one file, the **first** occurrence of a key wins, not the last - if you appended a new value instead of editing the existing line, the old one is still what's used.                                                                              |
| A trailing slash on `ORBOTO_BASE_URL` seems to matter, or doesn't                                    | It doesn't - the CLI trims a trailing slash automatically, so `https://acme.example.com/api` and `https://acme.example.com/api/` behave identically. If requests still fail, the problem is elsewhere (wrong host, missing `/api`, etc.), not the slash. |


# API cookbook (/api-cli/cookbook)



All examples use an API key: `Authorization: Bearer orb_...`. The
interactive OpenAPI reference at `https://<your-instance>/docs` documents
every route and schema.

## Create a ticket [#create-a-ticket]

The project is a path parameter, not a body field - `title` is the only
required field in the body, everything else is optional:

```bash
curl -X POST https://acme.example.com/api/projects/<projectId>/tickets \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"fix: flux capacitor drifts","type":"bug","priority":"high"}'
```

The response is the full ticket object; a trimmed example of what comes
back:

```json
{
  "id": "3fa0c2e1-...",
  "projectId": "b1a9...",
  "ticketKey": "ACME-51",
  "ticketNumber": 51,
  "title": "fix: flux capacitor drifts",
  "type": "bug",
  "priority": "high",
  "status": "TODO",
  "statusCategory": "todo",
  "statusName": "To Do",
  "createdAt": "2026-08-30T09:12:04.000Z",
  "similarWarnings": []
}
```

`similarWarnings` is a non-empty array (not an error) when the new
ticket's title/description closely matches an existing one - the create
still succeeds, but you get the near-duplicate's key and similarity
score to review, the same signal the CLI's `create-ticket` surfaces as a
warning.

**Don't have the project's UUID?** Resolve it once from the key and
reuse it - ticket reads also accept the key form directly within a
project (`GET /projects/<projectId>/tickets/by-key/ACME-42`), so you
typically only need the project UUID, not every ticket's UUID:

```bash
curl "https://acme.example.com/api/projects/by-key/ACME" -H "Authorization: Bearer $ORBOTO_TOKEN"
# → { "id": "<project-uuid>", "key": "ACME", "name": "...", ... }
```

## Query with OQL [#query-with-oql]

```bash
curl -X POST https://acme.example.com/api/query \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{"oql":"project = ACME AND status = TODO AND priority = high","limit":25}'
```

Response shape:

```json
{
  "items": [ { "ticketKey": "ACME-51", "title": "...", "..." : "..." } ],
  "nextCursor": null
}
```

`nextCursor` is `null` when you've reached the end; otherwise pass it
back as `"cursor": "<value>"` in the next request body to get the
following page. See [OQL](/api-cli/oql) for the full grammar and
field list - `status` (legacy enum, uppercase values like `TODO`) and
`priority` (lowercase values like `high`) intentionally use different
casing conventions, so copy the exact case from the
[field reference](/api-cli/oql#field-reference) rather than
guessing.

## Comment and close [#comment-and-close]

Post a comment:

```bash
curl -X POST https://acme.example.com/api/tickets/<id>/comments \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{"content":"Fixed and verified."}'
```

Moving status is a two-step lookup-then-patch, because status ids are
per-project (a project can rename or reorder its workflow statuses), so
you resolve the target status id by name first:

```bash
curl "https://acme.example.com/api/projects/<projectId>/ticket-statuses" \
  -H "Authorization: Bearer $ORBOTO_TOKEN"
# → [{ "id": "...", "name": "Done", "category": "done" }, ...] - find the row you want
```

then PATCH the ticket with that id:

```bash
curl -X PATCH https://acme.example.com/api/projects/<projectId>/tickets/<id> \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{"statusId":"<the-status-id-from-above>"}'
```

The workflow's configured transitions apply exactly as in the UI - a
`400` comes back if the target status isn't reachable from the ticket's
current one, the same guardrail that stops a drag-and-drop move to an
invalid column on the board.

## Walk a paginated list [#walk-a-paginated-list]

Every list endpoint uses the same cursor shape - request a page, read
`nextCursor`, and keep going until it's `null`:

```bash
curl "https://acme.example.com/api/projects?limit=50" -H "Authorization: Bearer $ORBOTO_TOKEN"
# → { "items": [...50 rows...], "nextCursor": "eyJrIjoi..." }

curl "https://acme.example.com/api/projects?limit=50&cursor=eyJrIjoi..." -H "Authorization: Bearer $ORBOTO_TOKEN"
# → { "items": [...next 50 rows...], "nextCursor": null }   ← end of the list
```

The cursor is an opaque, signed token - never construct one by hand or
try to decode it for meaning; always pass back exactly what the previous
response gave you. A page always includes `nextCursor`, even on the very
last page (as `null`), so "keep paging while `nextCursor` is truthy" is
a correct loop condition without a separate "am I done" check.

## Upload an attachment [#upload-an-attachment]

Attachments are multipart uploads to the ticket's attachment route:

```bash
curl -X POST https://acme.example.com/api/tickets/<id>/attachments \
  -H "Authorization: Bearer $ORBOTO_TOKEN" \
  -F "file=@screenshot.png"
```

The response returns the stored file's metadata - `id`, `filename`,
`contentType`, `sizeBytes`, and a `downloadUrl`. **Store the attachment
id, not the download URL** - download links are short-lived; re-fetch
`GET /attachments/<id>` (or `.../base64` for inline bytes) whenever you
need the file again.

## Bulk update tickets [#bulk-update-tickets]

Apply one field change to many tickets in a single call instead of
looping over individual updates:

```bash
curl -X POST https://acme.example.com/api/projects/<projectId>/tickets/bulk \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{"ids":["<ticket-id-1>","<ticket-id-2>"],"action":"status","value":"<statusId>"}'
```

`action` is one of `status`, `milestone`, `assignee`, `due_date`,
`version`, `priority`; `value` is the new value for that field (a status
id, milestone id, user id, ISO date, version id, or priority string -
`null` clears an optional field, e.g. unassigning). The response is
`{"updated": N}` - the count of tickets actually changed. This needs
`project:edit` on the target project, same as any other ticket mutation.

For heterogeneous per-ticket changes (different fields per ticket), loop
individual `PATCH /tickets/<id>` calls instead - the bulk endpoint
applies one field/value pair across the whole id list.

## Register and consume a webhook [#register-and-consume-a-webhook]

Webhooks deliver workspace events (ticket created, comment posted, and
more) to a URL you control, HMAC-signed so you can verify each delivery.

**1. Register the webhook** on a project:

```bash
curl -X POST https://acme.example.com/api/projects/<projectId>/webhooks \
  -H "Authorization: Bearer $ORBOTO_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "ticket-sync",
    "url": "https://your-service.example.com/hooks/orboto",
    "events": ["ticket.created", "ticket.updated", "comment.created"]
  }'
```

This needs `project:edit` on the target project. The response includes
`secret` - a signing secret **shown once, at creation**. Store it
alongside the webhook id; there's no route to retrieve it again later
(only rotate it, which invalidates the old one).

**2. Verify each delivery.** Every request carries `X-Orboto-Event`
(the event name) and `X-Orboto-Signature: sha256=<hex-hmac>`, computed
as an HMAC-SHA256 of the raw request body using your webhook's secret.
Verify before trusting the payload:

```js
const crypto = require("crypto");

function isValidDelivery(secret, rawBody, signatureHeader) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}
```

Use the raw, unparsed request body for the HMAC input - re-serializing
parsed JSON can change byte-for-byte formatting and break the
comparison.

**3. Inspect available events.** `GET /admin/webhooks/events` returns
every event name, a description, and an example payload - useful for
building the consumer without guessing the shape.

**4. Debug and replay deliveries.** Every attempt (success or failure)
is logged:

```bash
curl https://acme.example.com/api/webhooks/<webhookId>/deliveries \
  -H "Authorization: Bearer $ORBOTO_TOKEN"

curl -X POST https://acme.example.com/api/webhooks/<webhookId>/redeliver/<deliveryId> \
  -H "Authorization: Bearer $ORBOTO_TOKEN"
```

Redelivery re-sends the exact original payload - handy after fixing a
consumer bug without waiting for the event to happen again.

Setting `payloadFormat` to `slack`, `microsoft_teams`, or `discord`
instead of the default `generic` reshapes the body for that chat tool's
incoming-webhook format; vendor-shaped deliveries skip the
`X-Orboto-Signature` / `X-Orboto-Event` headers since those tools don't
read them.

## Errors [#errors]

Errors carry a stable `errorKey` (machine-readable) alongside a
human-readable `error` message - branch on the key, display the message.

### Troubleshooting [#troubleshooting]

| Symptom                                                | Fix                                                                                                                                                                                                                             |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` on every call                                    | Check `Authorization: Bearer <key>` is present and the key hasn't been revoked or expired - mint a fresh one from your profile.                                                                                                 |
| `403` on a route that worked for another project       | Permissions are per-project. Confirm the API key's owner is actually a member of *this* project with the required permission, not just any project.                                                                             |
| Attachment upload returns `413` or `415`               | `413` is over the size limit; `415` is a content type the instance doesn't accept. Check your instance's configured limits.                                                                                                     |
| Bulk update returns `updated: 0`                       | The `ids` you sent didn't resolve to tickets you can edit in this project - a bulk call is silently a no-op on ids it can't touch, it never partially fails the *request*, only the *effect*.                                   |
| Webhook deliveries show as failing in the delivery log | Your endpoint must return a 2xx within the delivery timeout. Check the logged response status/body per delivery, fix the consumer, then use `redeliver` to replay the specific failed event instead of waiting for it to recur. |
| Signature verification always fails                    | Compare against the **raw** request body, not a re-stringified copy of the parsed JSON - whitespace and key order differences change the HMAC.                                                                                  |


# API & CLI (/api-cli)



orboto is API-first - the web app, the CLI, the MCP server and every
integration all speak the same REST API with the same permissions.

## The REST API [#the-rest-api]

* Interactive OpenAPI reference: `https://<your-instance>/docs` on any
  running instance - every route, schema and response, generated from the
  live server.
* Authenticate with an API key (`orb_*`, minted in your profile or by an
  admin for bot accounts) sent as `Authorization: Bearer <key>`.
* List endpoints use cursor pagination: pass `?cursor=<opaque>&limit=50`,
  read `items` + `nextCursor` from the response.

## For LLMs [#for-llms]

These docs are machine-readable: [`/llms.txt`](/llms.txt) is the index,
[`/llms-full.txt`](/llms-full.txt) the full text, and every page has a raw
Markdown twin via the page-actions menu (Copy as Markdown, Open in
ChatGPT/Claude).

<Cards>
  <Card title="Install the CLI" href="/api-cli/cli" description="A single static binary over the whole API - install, configure, update." />

  <Card title="CLI daily workflow" href="/api-cli/cli-usage" description="The full command set - tickets, sessions, bulk ops, generic verbs." />

  <Card title="OQL query language" href="/api-cli/oql" description="Typed ticket queries - filters, sorting, JQL flavor." />

  <Card title="API cookbook" href="/api-cli/cookbook" description="Create, query, attach, bulk-update, and consume webhooks." />
</Cards>


# OQL query language (/api-cli/oql)



OQL is a typed, ACL-aware query language for tickets. It's the canonical way to express filter combinations that the per-entity list endpoints (`/projects/:id/tickets?status=…&assignee=…`) can't reach without growing yet another querystring parameter.

OQL also accepts JQL syntax through a thin compatibility adapter - paste a JQL query, get the same result.

***

## At a glance [#at-a-glance]

```
project = ACME AND assignee = currentUser() AND statusCategory != done
ORDER BY priority DESC, dueDate ASC
LIMIT 25
```

* **Endpoint:** `POST /query` (cursor-paginated, rate-limited at 60/min/user).
* **Surface:** REST endpoint, MCP tool `orboto_query`, CLI shortcut `orboto query "<oql>"`, ⌘K palette OQL toggle.
* **Authorisation:** every query starts from a project-membership join + private-ticket guard. External users get `is_private = false` hard-pinned regardless of how the OQL is shaped.

***

## Writing your first query [#writing-your-first-query]

If you've never written OQL before, build it up one clause at a time
rather than reading the grammar cold. Every example below is real and
runnable through any [surface](#surfaces).

**Start with one condition.** A query is just `field operator value`:

```
assignee = currentUser()
```

This alone returns every ticket assigned to you, across every project
you're a member of - no `LIMIT`, no `ORDER BY`, nothing else required.
`currentUser()` is a function call that resolves to your own user id at
query time, so the same query text means "my tickets" for whoever runs
it.

**Add a second condition with `AND`.** Combine conditions the way you'd
expect from any query language:

```
assignee = currentUser() AND statusCategory != done
```

Now it's your tickets that aren't finished yet - `!=` excludes rather
than includes, and `statusCategory` is the four-value workflow bucket
(`todo` / `in_progress` / `in_review` / `done`) rather than a
project-specific status name, so this works the same regardless of how
any individual project labels its statuses.

**Sort the results.** `ORDER BY` goes after every filter condition, and
takes one or more fields with an optional direction (`ASC` is the
default when you omit it):

```
assignee = currentUser() AND statusCategory != done
ORDER BY priority DESC, dueDate ASC
```

This reads as "my open work, most urgent priority first, and for ties on
priority, whichever is due soonest."

**Cap how many rows come back.** `LIMIT` goes last:

```
assignee = currentUser() AND statusCategory != done
ORDER BY priority DESC, dueDate ASC
LIMIT 10
```

**Scope to a project, and search text.** Add `project = <key>` to
narrow to one project, and `~` for a case-insensitive substring match on
a text field:

```
project = ACME AND title ~ "timeout" AND statusCategory != done
```

**Check for something being missing.** `IS EMPTY` / `IS NOT EMPTY` on a
multi-valued field, and `IS NULL` / `IS NOT NULL` on a scalar one:

```
assignee IS EMPTY AND statusCategory = todo
```

That's the whole shape of the language: pick fields from the
[field reference](#field-reference) below, combine them with `AND` /
`OR` / `NOT` and parentheses for grouping, optionally sort and limit.
Everything past this point is reference material for the specific
fields, functions, and edge cases available to you.

***

## Grammar [#grammar]

Formal PEG grammar lives in `apps/api/src/services/oql/grammar.peggy`. Informally:

```
query        = expression (ORDER BY orderList)? (LIMIT integer)?
expression   = orExpr
orExpr       = andExpr (OR andExpr)*
andExpr      = notExpr (AND notExpr)*
notExpr      = NOT? predicate
predicate    = "(" expression ")"
             | field operator value
             | field "IN" "(" valueList ")"
             | field "IS" ("NOT")? ("NULL" | "EMPTY")
operator     = "=" | "!=" | "<" | "<=" | ">" | ">=" | "~" | "!~"
value        = stringLit | numberLit | dateLit | functionCall | identifier
functionCall = "currentUser()" | "now()" | "startOfWeek()" | "endOfWeek()"
             | "startOfMonth()" | "endOfMonth()" | "daysAgo(n)"
```

* Keywords (`AND`, `OR`, `NOT`, `IN`, `IS`, `NULL`, `EMPTY`, `ORDER`, `BY`, `LIMIT`, `ASC`, `DESC`) are case-insensitive and word-bounded - `andrew` is an identifier, not `AND` + `rew`.
* Strings: `"double"` or `'single'` quotes. Backslash-escapes `\"` and `\'` work.
* Identifiers: `[a-zA-Z0-9_][a-zA-Z0-9_-]*` - the trailing dashes let `ACME-42` parse as a bareword, and the leading-digit class lets digit-leading project keys like `10M` or `3D` parse without quoting. Pure-digit tokens still parse as numbers because `NumberLit` is tried first in value position.
* Dates: ISO format `"YYYY-MM-DD"` as a quoted string. Function calls return either ISO timestamps (`now()`, `daysAgo(n)`) or strings (`currentUser()` → user UUID).
* Empty input is valid and matches every visible row (subject to ACL).

***

## Field reference [#field-reference]

Grouped by what the field describes, so you can jump straight to the
category you need. Every field accepts the operators listed; anything
else returns 400 with `errorKey: errors.oql.unknown_field`.

### Identity [#identity]

| Field          | Type   | Operators             | Notes                                                                                                                                   |
| -------------- | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `key`          | string | `= != < <= > >= ~ !~` | Ticket key, e.g. `ACME-42`.                                                                                                             |
| `ticketNumber` | number | `= != < <= > >= ~ !~` | Integer half of `ticketKey` (ACME-42 → 42). Use this - not `key` - when sorting numerically, otherwise `ACME-10` lands before `ACME-2`. |
| `title`        | string | `= != ~ !~`           | Ticket title. `~` is case-insensitive substring match (ILIKE).                                                                          |
| `description`  | string | `= != ~ !~`           | Ticket description body. `COALESCE`d to empty string so `~` matches NULL rows correctly.                                                |

### Status, type, priority [#status-type-priority]

| Field                            | Type   | Operators             | Notes                                                                                                                                                                                      |
| -------------------------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`                         | enum   | `= != ~ !~`           | Legacy lifecycle enum (`TODO` / `IN_PROGRESS` / `IN_REVIEW` / `DONE` / `WONT_FIX`). Backed by `tickets.status`, kept in sync with the FK status's category.                                |
| `statusName`                     | string | `= != ~ !~`           | The display name of the ticket's current `ticket_status` row (e.g. `"In Progress"`). Use this for projects with custom workflow names.                                                     |
| `statusCategory`                 | enum   | `= !=`                | Workflow bucket: `todo` / `in_progress` / `in_review` / `done`.                                                                                                                            |
| `priority`                       | enum   | `= !=`                | `blocker` / `high` / `normal` / `low` / `trivial`.                                                                                                                                         |
| `priorityLevel`, `severityLevel` | number | `= != < <= > >= ~ !~` | Numeric mapping of `priority`: blocker=5, high=4, normal=3, low=2, trivial=1. Higher = more important. Use for `priorityLevel >= 4` ("high or blocker") and ORDER BY. Both names accepted. |
| `type`                           | enum   | `= !=`                | `task` / `bug` / `story` / `epic`.                                                                                                                                                         |

### People [#people]

| Field                   | Type               | Operators                                      | Notes                                                                                                                                                                                                                          |
| ----------------------- | ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `assignee`              | identifier (multi) | `=` (membership) · `IN (…)` · `IS [NOT] EMPTY` | Resolves by UUID, exact email, OR case-insensitive full name. `IS EMPTY` = unassigned.                                                                                                                                         |
| `reporter`, `createdBy` | identifier         | `= !=`                                         | `tickets.created_by`. Both names accepted. Resolves by UUID, exact email, OR case-insensitive full name. A value matching no user returns an empty result set (never an error); ambiguous names match any user with that name. |
| `reporterType`          | enum               | `= !=`                                         | `guest` / `internal` - is the ticket's creator an external (guest) account? `reporterType = guest` pulls up everything filed by guests without listing each guest's email.                                                     |
| `assigneeType`          | enum               | `= !=`                                         | `guest` / `internal` - `guest` when the ticket has at least one external assignee; `internal` is the exact complement (all-internal or unassigned).                                                                            |

### Labels, dependencies, git [#labels-dependencies-git]

| Field                    | Type               | Operators                                      | Notes                                                                                                                                                                                                         |
| ------------------------ | ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labels`                 | identifier (multi) | `=` (membership) · `IN (…)` · `IS [NOT] EMPTY` | Match by label name.                                                                                                                                                                                          |
| `dependsOn`, `blockedBy` | identifier (multi) | `=` (membership) · `IN (…)` · `IS [NOT] EMPTY` | Match the depended-on ticket by UUID or ticketKey. `IS EMPTY` = no dependencies. Both names mean the same direction (A depends on B = A is blocked by B).                                                     |
| `hasGitActivity`         | boolean            | `= !=`                                         | True when the ticket has any linked commit, PR, or issue event in `git_activities`.                                                                                                                           |
| `waitingForGitIngestion` | boolean            | `= !=`                                         | True when the ticket is `in_review`, has zero `git_activities` rows, AND the project has an active git connection - a stalled-ingestion signal distinct from a ticket that's simply not linked to any commit. |

### Organization [#organization]

| Field       | Type    | Operators         | Notes                                                                             |
| ----------- | ------- | ----------------- | --------------------------------------------------------------------------------- |
| `milestone` | string  | `= !=` · `IN (…)` | Milestone key (`ACME-M3`), display name, or UUID. Use the key when names collide. |
| `version`   | string  | `= !=`            | Version display name.                                                             |
| `project`   | string  | `= !=`            | Project key (e.g. `ACME`) or display name.                                        |
| `parentKey` | string  | `= !=`            | Parent ticket's key - useful for walking an epic into its children.               |
| `isPrivate` | boolean | `= !=`            | `true` / `false`.                                                                 |

### Dates [#dates]

| Field                                                        | Type | Operators             | Notes                                                  |
| ------------------------------------------------------------ | ---- | --------------------- | ------------------------------------------------------ |
| `dueDate`, `startDate`, `closedAt`, `createdAt`, `updatedAt` | date | `= != < <= > >= ~ !~` | ISO date strings or function values like `daysAgo(7)`. |

### Effort and time [#effort-and-time]

| Field                     | Type   | Operators             | Notes                                                                                                                                                                                               |
| ------------------------- | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `estimatedTimeMinutes`    | number | `= != < <= > >= ~ !~` | Integer minutes.                                                                                                                                                                                    |
| `loggedMinutes`           | number | `= != < <= > >= ~ !~` | Computed via correlated SUM over `time_entries`; expensive on huge time tables.                                                                                                                     |
| `progress`, `donePercent` | number | `= != < <= > >= ~ !~` | `loggedMinutes / estimatedTimeMinutes * 100`. NULL when estimate is missing or zero - `progress IS NULL` finds unestimated tickets. Uncapped: values > 100 mean "over budget". Both names accepted. |

***

## Function reference [#function-reference]

| Function                         | Returns       | Notes                          |
| -------------------------------- | ------------- | ------------------------------ |
| `currentUser()`                  | string (UUID) | The requester's user id.       |
| `now()`                          | ISO timestamp | Wall-clock at translate time.  |
| `startOfWeek()`, `endOfWeek()`   | ISO timestamp | Monday-start week, UTC.        |
| `startOfMonth()`, `endOfMonth()` | ISO timestamp | UTC month boundary.            |
| `daysAgo(n)`                     | ISO timestamp | `n` whole days before `now()`. |

The function whitelist is closed - anything else (`pg_sleep()`, `version()`, `current_user`, …) is rejected at translate time.

***

## Operators [#operators]

* `=`, `!=` - equality. For multi-valued fields (`assignee`, `labels`) this is membership.
* `<`, `<=`, `>`, `>=` - ordering on numbers and dates.
* `~`, `!~` - case-insensitive ILIKE. Pattern is automatically wrapped in `%…%`.
* `IN (a, b, c)` - equality against any of the listed values.
* `IS NULL` / `IS NOT NULL` - null checks on scalar fields.
* `IS EMPTY` / `IS NOT EMPTY` - multi-valued field has zero / non-zero rows.

***

## ORDER BY + LIMIT [#order-by--limit]

```
… ORDER BY priority DESC, dueDate ASC
… LIMIT 25
```

Multiple sort keys allowed. Direction defaults to `ASC` when omitted. The route appends `tickets.id` as a tie-breaker so cursor walks don't stutter.

`LIMIT` caps the page size at the source. The route also clamps to 200 - anything larger is silently capped.

***

## Cookbook [#cookbook]

```
# My open work, blockers first
assignee = currentUser() AND statusCategory != done
ORDER BY priority DESC, dueDate ASC

# Tickets I touched this week
assignee = currentUser() AND updatedAt >= daysAgo(7)
ORDER BY updatedAt DESC

# Anything blocking ORB this week
project = ACME AND priority IN (blocker, high) AND dueDate <= endOfWeek()

# Unowned bugs in the backlog
labels = bug AND assignee IS EMPTY AND statusCategory = todo

# At-risk for budget - logged exceeds estimate
loggedMinutes > estimatedTimeMinutes AND statusCategory != done

# Children of an epic
parentKey = ACME-200 ORDER BY ticketKey ASC

# Tickets shipped in the last sprint
statusCategory = done AND closedAt >= startOfMonth() AND closedAt < endOfMonth()

# Stale review queue - sitting in review for 3+ days
statusCategory = in_review AND updatedAt <= daysAgo(3)

# All my assigned bugs in the current quarter
assignee = currentUser() AND labels = bug AND createdAt >= startOfMonth()

# Free-text contains in a ticket key prefix
key ~ "ACME-2"

# Everything filed by guests across my projects
reporterType = guest ORDER BY createdAt DESC

# Open tickets that have a guest assignee
assigneeType = guest AND statusCategory != done

# All guest-related tickets (reported by OR assigned to a guest)
reporterType = guest OR assigneeType = guest
```

***

## JQL compatibility [#jql-compatibility]

Pass `syntax: 'jql'` (or `--syntax=jql` from the CLI) to accept JQL-flavoured input. The adapter pre-rejects unsupported tokens then translates the survivor through the OQL parser with field/value renames applied.

### Field aliases (JQL → OQL) [#field-aliases-jql--oql]

| JQL          | OQL              |
| ------------ | ---------------- |
| `due`        | `dueDate`        |
| `created`    | `createdAt`      |
| `updated`    | `updatedAt`      |
| `resolved`   | `closedAt`       |
| `resolution` | `statusCategory` |
| `sprint`     | `milestone`      |
| `issuetype`  | `type`           |

### Value aliases on `resolution` / `statusCategory` [#value-aliases-on-resolution--statuscategory]

| JQL value       | OQL value     |
| --------------- | ------------- |
| `Done`          | `done`        |
| `Unresolved`    | `todo`        |
| `"In Progress"` | `in_progress` |

### Unsupported features (and what to do instead) [#unsupported-features-and-what-to-do-instead]

| JQL feature        | Suggested OQL                                                     |
| ------------------ | ----------------------------------------------------------------- |
| `WAS`              | `updatedAt >= daysAgo(30)` (we don't track historic field values) |
| `CHANGED`          | `updatedAt >= daysAgo(7)`                                         |
| `issueHistory()`   | None; the audit log surface is the closest analogue.              |
| `votes`            | `priority` or labels for marking importance.                      |
| `workRatio`        | `loggedMinutes > estimatedTimeMinutes`.                           |
| `attachments`      | Not queryable; surfaced on the ticket detail.                     |
| `originalEstimate` | `estimatedTimeMinutes` (orboto only stores the current estimate). |
| `cf[…]`            | Not supported - orboto has no custom-field schema.                |

Each unsupported token produces a 400 with `errorKey: errors.jql.unsupported_feature` carrying a `suggestion` field the UI surfaces verbatim.

***

## Endpoint [#endpoint]

```
POST /query
Authorization: Bearer <token>
Content-Type: application/json

{
  "oql": "project = ACME AND assignee = currentUser()",
  "syntax": "oql",      // or "jql" - defaults to "oql"
  "cursor": "...",      // opaque, from a previous response.nextCursor
  "limit": 25           // 1-200, default 25
}
```

Response:

```json
{
  "items": [Ticket, ...],
  "nextCursor": "opaque-token-or-null",
  "queryPlan": { "sql": "...", "params": [], "ast": {...} }   // ?explain=true, super-admin only
}
```

### Errors [#errors]

All 4xx errors follow the `ErrorResponseSchema` shape (`error`, `errorKey`, `errorParams`):

| Status | errorKey                          | When                                                                                       |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------ |
| 400    | `errors.oql.parse`                | Syntax error. `errorParams` carries `line`, `column`, `expected`, `message`.               |
| 400    | `errors.oql.unknown_field`        | Field not in the whitelist.                                                                |
| 400    | `errors.oql.unknown_function`     | Function not in the whitelist.                                                             |
| 400    | `errors.oql.unsupported_operator` | Operator can't be applied to that field.                                                   |
| 400    | `errors.oql.invalid_value`        | Type coercion failed (e.g. malformed date, enum value not in allow-list).                  |
| 400    | `errors.oql.wrong_arity`          | Function called with the wrong number of arguments.                                        |
| 400    | `errors.jql.unsupported_feature`  | JQL adapter rejected an unsupported token. `errorParams` carries `token` + a `suggestion`. |
| 401    | `errors.common.unauthorized`      | Missing / invalid bearer token.                                                            |
| 429    | `errors.common.rate_limited`      | More than 60 calls / minute / user.                                                        |

### `?explain=true` [#explaintrue]

Super-admin only. Adds `queryPlan: { sql, params, ast }` to the response so an operator can debug "why does my OQL return 0 rows" without database access. Non-admins receive the same 200 response without the field - no leak that the param exists.

***

## Troubleshooting [#troubleshooting]

| Symptom                                                  | Likely cause                                                                                                                                                                                                                  |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors.oql.unknown_field` on a field you're sure exists | Check spelling and case - fields are case-sensitive (`statusCategory`, not `StatusCategory`). Confirm it's in the [field reference](#field-reference) above; custom fields aren't supported (see [Roadmap](#roadmap)).        |
| Query parses but returns 0 rows unexpectedly             | Authorisation is applied before your filter (see below) - you only ever see tickets your account can already see. As a super-admin, add `?explain=true` to inspect the generated SQL.                                         |
| `ACME-10` sorts before `ACME-2`                          | Sort on `ticketNumber`, not `key` - `key` sorts as text.                                                                                                                                                                      |
| A date comparison silently matches nothing               | Dates must be quoted ISO strings (`"2026-01-15"`) or a function call (`daysAgo(7)`) - a bare unquoted date is parsed as an identifier and fails field lookup.                                                                 |
| JQL input rejected with `errors.jql.unsupported_feature` | The adapter has a closed alias list ([field aliases](#field-aliases-jql-oql), [unsupported features](#unsupported-features-and-what-to-do-instead)). The error's `suggestion` field names the OQL equivalent to use directly. |
| `errors.common.rate_limited`                             | More than 60 calls/minute for the user. Batch reads with a wider `LIMIT` and cursor pagination instead of polling in a tight loop.                                                                                            |

***

## Authorisation [#authorisation]

The translator embeds the auth pipeline into the WHERE clause as the FIRST predicate, in this exact order:

1. **Project membership** - `EXISTS project_members WHERE user_id = :requester`. Super-admin bypass collapses to `TRUE`.
2. **Private-ticket visibility** - `is_private = false OR EXISTS ticket_access_acl OR has-global ticket:view_private`.
3. **External-user hard pin** - when the user row has `is_external = true`, `is_private = false` is appended LAST. No OQL clause can widen the filter past this guard.

Every query - `*` SELECT, `IS NULL`, OR-of-everything - runs with this predicate AND-ed in. The translator's security tests assert this contract.

***

## Surfaces [#surfaces]

| Surface              | How                                                                                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **REST**             | `POST /query` (this doc).                                                                                                                                               |
| **CLI shortcut**     | `orboto query "<oql>" [--syntax=oql\|jql] [--limit=25] [--cursor=...] [--explain]` - see the [CLI daily workflow](/api-cli/cli-usage#milestones-docs-and-search).       |
| **MCP tool**         | `orboto_query` - same input shape, structuredContent envelope mirrors the REST response.                                                                                |
| **⌘K palette**       | OQL toggle next to the AI toggle. Errors render inline with line/column. "Save as bookmark" persists the OQL via `saved_searches.oql`.                                  |
| **Saved searches**   | `saved_searches.query_type ENUM ('legacy', 'oql', 'jql')` + `saved_searches.oql TEXT`. New bookmarks are oql/jql; old structured bookmarks keep working under `legacy`. |
| **AI search bridge** | `/search/nl` returns the equivalent OQL string in `response.oql` - the palette shows it under the chip row with an "Edit in OQL" button that pre-fills the OQL input.   |

{/* screenshot: the palette's OQL toggle with a query typed in and results below */}

***

## Performance notes [#performance-notes]

* The translator is pure-function and \< 1 ms per call. The compiled peggy parser caches at module-load.
* `loggedMinutes` uses a correlated SUM over `time_entries`; on workspaces with millions of time entries this slows queries that filter on it. A materialised view is the planned escape hatch when the slow-query threshold trips.
* ORDER BY on text fields (`title`, `key` via `~`) doesn't use the search-vector index - keep complex text searches on the dedicated `/search` endpoint and use OQL for the structured filter combinations.
* The cursor is `(updated_at, id)` tuple-comparison so default-ordered queries paginate efficiently. Custom ORDER BY queries pay an in-memory sort if the order doesn't match an existing index.

***

## Roadmap [#roadmap]

Out of scope for v1 (intentionally):

* Multi-entity queries (`FROM tickets, comments`).
* Aggregation (`COUNT`, `SUM`, `GROUP BY`) - the analytics endpoints already cover those.
* Update queries (`UPDATE tickets SET status = ...`) - too dangerous for a public DSL.
* Custom-field schema - not in the data model.
* Free-text body search - stays on `/search`.
* Query history / performance insights.

If any of these become hard requirements, let us know.


# Concepts and glossary (/getting-started/concepts)



Welcome to orboto - a place for teams to plan work, track it, and talk about it. This guide is written for the people who *use* orboto every day: it explains, task by task, how to get things done. You do not need to be technical to follow it.

If you are brand new, start with [Getting started](/getting-started) and [Your first project](/getting-started/first-project). Otherwise, jump straight to the chapter you need, or use this page as a reference glossary whenever a term is unfamiliar.

> **A note on what you can see.** What appears in your sidebar and on your screens depends on your **role** and **permissions**. If this guide describes a button or page you cannot find, your workspace administrator has not granted you access to it. That is normal - it is not a fault. Administrator-only features (managing users, single sign-on, imports, backups, and so on) are covered separately; this guide points to that material where relevant rather than duplicating it.

## Contents [#contents]

1. [Getting started](/getting-started) - signing in, the layout of the screen, themes, language, and keyboard shortcuts.
2. [Your first project](/getting-started/first-project) - a hands-on walkthrough: create a project, add a ticket, move it across the board.
3. [Your dashboard](/user-guide/everyday/dashboard) - your personal home page and its widgets.
4. [Projects and tickets](/user-guide/work/projects-and-tickets) - the core: projects, the five board views, and everything a ticket can do.
5. [Search](/user-guide/knowledge/search) - global search, the query language, saved searches, and AI search.
6. [Docs and wiki](/user-guide/knowledge/docs-and-wiki) - spaces, pages, smart links, sharing, and asking questions of your docs.
7. [Time tracking](/user-guide/planning/time-tracking) - the stopwatch, time calendar, timesheets, absences, and capacity.
8. [Planning and alerts](/user-guide/planning/planning-and-alerts) - milestones, versions, project templates, and alert rules.
9. [Analytics](/user-guide/analytics) - burndown, velocity, flow metrics, forecasting, and earned value.
10. [Notifications](/user-guide/everyday/notifications) - the inbox, preferences, and chat channels.
11. [Account and security](/user-guide/everyday/account-and-security) - your profile, password, two-factor authentication, passkeys, and sessions.
12. [AI assistant](/user-guide/ai-assistant) - the built-in chat assistant and the AI features across the product.
13. [Customers and guests](/user-guide/customers-and-guests) - external organisations and the guest experience.
14. [Integrations](/integrations) - connecting AI clients, code repositories, and chat tools, plus admin pointers.
15. [Requirements documents and reports](/user-guide/knowledge/requirements-documents) - making a project ready for a requirements specification (Pflichtenheft) and a customer report, and which project data fills which chapter.

## How the pieces fit together [#how-the-pieces-fit-together]

Before the glossary, the short version of how everything nests:

* **Workspace** - your whole orboto instance, shared by your team.
  * **Project** (key `ACME`) - a container for related work.
    * **Milestone** - a checkpoint (a phase, a sprint) that groups tickets toward a date.
    * **Ticket** (key `ACME-42`) - one unit of work, living in exactly one project and optionally one milestone.
      * **Comments**, **checklists**, **attachments**, and **time entries** all live on a ticket.
    * **Doc space** - a folder of documentation pages that can reference the project's tickets via smart links.

Everything else in the glossary below is a property of, or an action on, one of these.

## Glossary [#glossary]

### Core work items [#core-work-items]

* **Project** - a container for related work, with a short **key** (for example `ACME`) that prefixes its tickets.
* **Ticket** - one unit of work: a task, a bug, a story, or an epic. Identified by a key like `ACME-42`.
* **Task** - a ticket type for a standalone unit of work with no further breakdown.
* **Bug** - a ticket type for something that is broken and needs fixing.
* **Story** - a ticket type for a piece of user-facing functionality, often broken down into smaller tasks.
* **Epic** - a ticket type for a large piece of work that groups several smaller tickets under it as children.
* **Status** - the stage a ticket is in (for example To Do, In Progress, Done); the columns on the Kanban board. Configurable per project.
* **Priority** - how urgent a ticket is (for example blocker, high, normal, low, trivial).
* **Label** - a coloured tag you attach to tickets to categorise them.
* **Assignee** - a person responsible for a ticket. A ticket can have several.
* **Checklist** - a list of smaller steps on a ticket; an item can link to another ticket so it ticks itself off when that ticket closes.
* **Parent / sub-ticket** - a ticket can have a parent and children, for breaking an epic or story into smaller pieces.
* **Dependency** - a relationship where one ticket **blocks** or is **blocked by** another.
* **RACI** - a way to record who is **Responsible** (does the work), **Accountable** (owns the outcome), **Consulted** (gives input), and **Informed** (kept in the loop).

### Board views [#board-views]

* **Kanban** - a board of cards in status columns that you drag work across.
* **List** - a compact, sortable, groupable table of tickets.
* **Gantt** - a timeline view placing tickets by their start and due dates, with dependency links drawn between bars.
* **Network** - a diagram of tickets connected by their dependencies - the fastest way to spot a blocker chain.

### Planning [#planning]

* **Milestone** - a meaningful checkpoint in a project (a phase, a sprint, a deliverable) that groups tickets toward a shared goal and date. Key form: `ACME-M3`.
* **Version** - a planned release of your product, with a target release date, bundling the work shipped together.
* **Template** - a reusable project or milestone structure you can apply to a new project.
* **Alert** - an automatic warning that fires when something needs attention (a deadline at risk, a budget nearing its limit).

### Time and capacity [#time-and-capacity]

* **Timesheet** - your logged time for a period, gathered for approval.
* **Absence** - a period of time off (holiday, sick leave, and so on), counted in working days.
* **Capacity** - the available working time a person has, compared against assigned and logged time.

### Analytics [#analytics]

* **Velocity** - how much work the team completes per period; used to plan future work.
* **Cycle time** - how long a ticket takes from start to done.
* **Burndown** - a chart of remaining work over time against an ideal line.
* **Cumulative flow diagram** - a chart of how many tickets sit in each status over time, showing where work piles up.
* **Delivery forecast** - a projected completion range and confidence level for a set of tickets, based on your team's actual pace.
* **Earned value (EVM)** - a standard method for checking whether progress matches the schedule and spend it should have bought.

### Knowledge [#knowledge]

* **Space** - a folder of related documentation pages.
* **Doc** - a single documentation page, written with the same rich-text editor as tickets.
* **Smart link** - a live link (typed with `[[`) to a ticket, doc, project, or milestone that always shows the target's current title.
* **Ask AI** - a panel that answers a question about your docs, with links back to the source pages it used.

### Notifications [#notifications]

* **Notification** - a message telling you something happened to your work, delivered in-app, by email, or to a chat channel.
* **Notification channel** - an external destination (such as a chat tool) subscribed to receive notifications, configured per workspace.

### Security and access [#security-and-access]

* **Role** - the set of permissions assigned to a member; what you can see and do is derived from it.
* **Permission** - a single granted capability (for example, creating projects or managing users).
* **Two-factor authentication (2FA)** - a second sign-in step beyond your password, using an authenticator app or a passkey.
* **Passkey** - a sign-in method using your device's fingerprint, face, or PIN instead of a code.
* **Single sign-on (SSO)** - signing in through your organisation's central identity provider.
* **Guest / external user** - someone outside your team given narrow access to specific shared content.

### AI and integrations [#ai-and-integrations]

* **AI assistant** - the in-app chat assistant that can answer questions and take actions on your behalf, with your confirmation.
* **MCP (Model Context Protocol)** - the standard that lets AI clients such as Claude Desktop or Cursor connect to orboto.

## Troubleshooting [#troubleshooting]

**A term in this guide doesn't match what I see in the app - for example, my board has no "To Do" column.**
Cause: statuses and workflows are configurable per project, so an administrator may have renamed, reordered, or removed a default one.
Fix: check the project's **Settings → Statuses** tab, or ask whoever manages the project.


# Create your first project and ticket (/getting-started/first-project)



This page is the fastest way to get a feel for orboto: create a project, add a ticket to it, and move that ticket across the board - with every field along the way explained, not just clicked through. Fifteen minutes, start to finish.

You need to be signed in already - see [Getting started](/getting-started) if you have not signed in yet.

## 1. Create a project [#1-create-a-project]

A **project** is the container everything else lives in: tickets, milestones, docs spaces, and members all belong to exactly one project (unless a workspace-wide feature explicitly says otherwise).

1. Select **Projects** in the sidebar.
2. Select **New project**.
3. Fill in the form:
   * **Name** - the full, human-readable name (for example "Website Relaunch"). This is what shows everywhere in menus and titles.
   * **Key** - a short project code, 2 to 10 letters or digits (for example `WEB`). Every ticket you create afterwards is numbered under this key (`WEB-1`, `WEB-2`, ...), so pick something short and permanent - you can rename the project later, but changing its key is disruptive because it re-numbers every reference to every ticket. Lowercase is fine to type; it is stored as uppercase automatically. If the key you type is already used by another project in your workspace, the form tells you before you can save.
   * **Description** (optional) - shown on the project card and its overview; use it to say what the project is for.
   * **Customer** (optional) - link the project to a customer record if your workspace tracks external customers. This is what makes the project eligible for [guest access](/user-guide/customers-and-guests) later.
4. Select **Save**.

{/* screenshot: the new-project form with name, key and description fields */}

You land on the new project, currently empty, showing the Kanban board. You can refine members, statuses, and labels later in its settings - see [Project settings](/user-guide/work/projects-and-tickets#project-settings-a-quick-tour). None of that is required to start working; a freshly created project is automatically seeded with a usable set of default statuses (To Do, In Progress, In Review, Done), so the board works immediately.

> **Don't see New project?** Project creation is a permission your workspace administrator grants, separately from being able to work inside projects you're already a member of. Ask them to either grant it to you or create the first project and add you as a member - everything below still applies once you have a project open, whoever created it.

## 2. Create a ticket [#2-create-a-ticket]

A **ticket** is one unit of work, always living inside exactly one project.

1. In your new project, select **New ticket**.
2. Fill in the form:
   * **Title** - the only field you must fill in. Keep it short and specific; you write the details in the description below.
   * **Type** - `task`, `bug`, `story`, or `epic`. This only changes the icon shown on the card and what you can filter by later - it doesn't restrict what you can do with the ticket. Pick `epic` if this piece of work is going to be broken down into several smaller tickets under it; pick `task` for anything else if you're not sure.
   * **Priority** - `blocker`, `high`, `normal`, `low`, or `trivial`. Drives sort order, filtering, and (if your admin has configured them) SLA response-time targets and alerts.
   * **Milestone** / **Version** (optional) - only shown once you've created at least one in this project; both default to empty. Leave them unset for now - see [Planning and alerts](/user-guide/planning/planning-and-alerts) when you're ready to schedule work.
   * **Estimate** (optional) - how long you expect the work to take. Feeds the Gantt view and capacity comparisons once you start using those.
3. Add a description with the rich-text editor if you want more detail - it supports formatting, pasted images, and `@mentions`, exactly like a comment.
4. Select **Save**.

{/* screenshot: the new-ticket form filled in with a title and a type selected */}

The ticket now shows on the board as `WEB-1` (or whichever key your project uses) as a card in the first status column - usually **To Do**. Selecting the card opens the full **ticket detail** panel, where every field above is editable again, plus the comment thread, checklists, attachments, and the rest of what a ticket can carry - covered in full in [Projects and tickets](/user-guide/work/projects-and-tickets).

> **Faster capture.** Switch the project to **List*&#x2A; view. Under any milestone group (or "No milestone"), a dashed **+ Add ticket** row expands into a compact inline form - type, title, due date, and assignee, no description or priority. Press Enter to create it and the row stays open with a cleared title, so you can bang out several tickets in a row without reopening the full dialog each time. Open any of them afterwards to fill in the rest.

## 3. Move it across the board [#3-move-it-across-the-board]

Open the **Kanban** view (the default) and drag the ticket's card from **To Do** into **In Progress**, and eventually into **Done**. Dropping a card into a different column immediately changes the ticket's **status** field - there is no separate save step, and the change is visible to every other member of the project in real time.

You can achieve the exact same result without dragging: open the ticket and change its **Status** field directly from the sidebar. Use whichever is faster for you - dragging one card on the board, or changing status from inside a ticket you already have open.

{/* screenshot: dragging a ticket card from To Do into In Progress on the Kanban board */}

## 4. Comment and mention a teammate [#4-comment-and-mention-a-teammate]

Open the ticket and scroll to the **comment thread** at the bottom. Type a comment, format it with the toolbar if you like, and type `@` followed by a name to mention a teammate - typing `@` opens an autocomplete list of project members, and selecting one inserts the mention and, once you post the comment, sends that person a notification. This is the normal way work gets discussed in orboto instead of a side channel: the discussion stays attached to the ticket forever, instead of scattered across chat history.

## 5. Optional: log time against it [#5-optional-log-time-against-it]

If your workspace tracks time, open the ticket and look for the timer control in its sidebar - start it while you work and stop it when you're done, or add a manual time entry with a specific date and duration if you're logging after the fact. See [Time tracking](/user-guide/planning/time-tracking) for the full picture - the stopwatch, the time calendar, and timesheets.

## Where to go next [#where-to-go-next]

* The full picture of projects, views, and everything a ticket can do: [Projects and tickets](/user-guide/work/projects-and-tickets)
* Every term you just met, explained: [Concepts and glossary](/getting-started/concepts)
* Find anything fast across your whole workspace: [Search](/user-guide/knowledge/search)
* Write documentation alongside your work: [Docs and wiki](/user-guide/knowledge/docs-and-wiki)

## Troubleshooting [#troubleshooting]

**The status column I want isn't on the board.**
Cause: your administrator can mark some statuses as hidden on the board by default, to keep it tidy for everyday use.
Fix: look for a **Show hidden columns** toggle above the board and turn it on - it also shows how many tickets are tucked away in hidden columns.

**I created a ticket but can no longer find it in the list.**
Cause: the filter bar above the board keeps whatever filter you last set (type, priority, milestone, and so on), and your new ticket may not match it - a common trap is a stale milestone filter after you leave the milestone field unset.
Fix: select **Clear** on the filter bar to reset every filter at once.

**The Milestone or Version dropdown is empty.**
Cause: nothing has been created yet in this project - both are optional and set up per project, not pre-populated.
Fix: leave it unset and create milestones/versions later in project settings, or skip straight to [Planning and alerts](/user-guide/planning/planning-and-alerts).

**The project key I typed was rejected.**
Cause: keys must be 2 to 10 letters or digits, and must be unique within your workspace - another project may already hold it.
Fix: try a different, still-short key; the form tells you immediately if there's a collision.


# Getting started (/getting-started)



This chapter gets you from "I have a link to orboto" to "I know my way around the screen". If you have never used orboto before, read this first, then jump to whichever chapter matches what you want to do.

## What orboto is [#what-orboto-is]

orboto is a place for teams to plan work, track it, and talk about it. Work is organised into **projects**. Inside a project you create **tickets** - a ticket is a single unit of work such as a task, a bug, a larger story, or an **epic** (a big piece of work that groups several smaller tickets). You move tickets across a board as the work progresses, discuss them in comments, attach files, log the time you spend, and watch progress on charts.

Everything you can reach depends on your **role** and **permissions**. If a link or button described in this guide is not visible to you, your workspace administrator has not granted you access to that area - that is expected, not a bug.

## Signing in [#signing-in]

{/* screenshot: the sign-in screen with email, password and the single-sign-on button */}

1. Open the workspace address your administrator gave you.
2. Enter your email and password, then select **Sign in**.
3. If your workspace uses **single sign-on** (SSO - logging in through your company's central identity provider, such as your Google or Microsoft work account), select the SSO button instead of typing a password, and complete the login in the window that opens.

### If you are asked for a second step [#if-you-are-asked-for-a-second-step]

If your account has **two-factor authentication** turned on (an extra security step beyond your password), after your password you are asked for one more thing:

* **A code** from your authenticator app - open the app on your phone and type the six-digit code.
* **A passkey** - your device prompts you for your fingerprint, face, or device PIN.
* **A recovery code** - if you cannot reach your phone, select the backup-code option and enter one of the one-time recovery codes you saved when you set two-factor up.

Setting up two-factor authentication for your own account is covered in [Account and security](/user-guide/everyday/account-and-security).

### Accepting an invitation [#accepting-an-invitation]

If you were invited to the workspace by email:

1. Open the invitation email and select the join link.
2. Set your name and a password (or continue with SSO if offered).
3. You land directly in the workspace.

### Resetting a forgotten password [#resetting-a-forgotten-password]

1. On the sign-in screen, select **Forgot password**.
2. Enter your email. If an account exists, you receive a reset link by email.
3. Open the link and choose a new password.

## The workspace at a glance [#the-workspace-at-a-glance]

{/* screenshot: the full app shell - left sidebar, top bar with search, and main content area */}

Once you are in, the screen has three parts:

* **The left sidebar** is your main navigation. It lists the areas you have access to: Dashboard, Projects, Customers, Docs, Time, Capacity, Templates, Alerts, and (for administrators) Admin. You can collapse the sidebar to icons with the small arrow at the top of it, and it collapses automatically on narrow screens.
* **The top bar** holds the global **Search** button in the centre, and on the right: your running **timer**, the **AI assistant** button (if enabled), a **language** selector, the **notification bell**, and a **settings** gear for notification preferences.
* **The main area** shows whatever you selected in the sidebar.

At the very bottom of the sidebar is your **profile** area - your avatar, name, and email. Select it to open your profile settings. Next to it is the **sign out** button.

### Choosing light or dark mode [#choosing-light-or-dark-mode]

Near the bottom of the expanded sidebar is a small three-button switch: **Light**, **Dark**, and **System** (System follows whatever your operating system is set to). Your choice is remembered on this device and synced to your account.

{/* screenshot: the light / dark / system theme switch in the sidebar */}

### Changing the language [#changing-the-language]

Use the language selector in the top bar to switch the interface language. The change applies immediately.

### Setting your presence [#setting-your-presence]

If your workspace has presence turned on, a small coloured dot sits on your avatar. Select the dot to switch between **Online** and **Invisible**. Invisible hides your active status from teammates without signing you out.

## Keyboard shortcuts [#keyboard-shortcuts]

orboto has a few global shortcuts:

* **Cmd/Ctrl + K** - open global search.
* **Cmd/Ctrl + J** - open the AI assistant (when enabled for you).
* **?** - show the list of shortcuts.
* **Esc** - close the current dialog.

{/* screenshot: the keyboard shortcuts overlay opened with the question-mark key */}

## Troubleshooting [#troubleshooting]

**I don't see Admin, or a sidebar item my colleague has.**
Cause: what you see depends on your role and permissions, not on a bug or a missing installation step.
Fix: ask your workspace administrator to grant the relevant permission if you believe you need it.

**The reset-password email never arrives.**
Cause: either the address has no account, or the message landed in spam/junk.
Fix: check spelling and your spam folder; if it still doesn't show up, ask your administrator to confirm an account exists for that email.

**My authenticator code is always "invalid".**
Cause: authenticator codes are time-based, so a device clock that has drifted even a little makes every code wrong.
Fix: check your phone's clock is set to automatic/network time, then try again. If you are still locked out, use one of your saved recovery codes and set two-factor up again.

**My invitation link says it has expired or was already used.**
Cause: invitation links are only valid for a limited time and can only be accepted once.
Fix: ask whoever invited you to send a new invitation.

## Where to go next [#where-to-go-next]

* Create your first project and ticket: [Your first project](/getting-started/first-project)
* Plan and track work in depth: [Projects and tickets](/user-guide/work/projects-and-tickets)
* Find anything fast: [Search](/user-guide/knowledge/search)
* Write and organise knowledge: [Docs and wiki](/user-guide/knowledge/docs-and-wiki)
* Record your time and time off: [Time tracking](/user-guide/planning/time-tracking)
* Turn a project into a requirements specification or customer report: [Requirements documents and reports](/user-guide/knowledge/requirements-documents)
* Set up your account and security: [Account and security](/user-guide/everyday/account-and-security)


# orboto cloud (/cloud)



orboto cloud is the managed edition: the same product as self-hosted,
operated for you. Your workspace lives at its own address, and the
platform takes care of everything below the application layer - you sign
up, and there is no server, container, or database for you to think about
at any point afterwards.

## What cloud manages [#what-cloud-manages]

* **Hosting and TLS.** Your workspace runs on managed infrastructure and
  is reachable over HTTPS from the moment it's provisioned - there is no
  server to patch, no container image to pull, and no certificate to
  renew. Compare this with [self-hosting](/self-hosting), where you
  run Docker Compose yourself and put your own reverse proxy in front.
* **Updates.** New versions roll out to your workspace as
  **non-interrupting updates** by default - you don't see downtime, and
  you don't have to bump an image tag yourself. When a maintenance action
  genuinely could affect you (something more than a routine rolling
  update), you're notified in advance per the service terms before it
  happens. If your team needs to control exactly when a new version
  lands - for example to line it up with your own release testing - you
  can stay **pinned** to a specific version instead of following the
  rolling channel; ask support to set this for your workspace.
* **Backups.** The platform runs automatic backups of your workspace in
  the background, independently of anything you configure. On top of
  that, you keep the same self-service export tools as a self-hosted
  install: trigger a full backup on demand, or set up your own scheduled
  jobs against your own S3-compatible bucket, from
  [Admin → Backup](/admin/operations/backup). Cloud does not remove
  this admin area - it adds a second, platform-side safety net on top of
  it.
* **Email.** Outbound email (invitations, notifications, password resets)
  works immediately with no setup - there is no SMTP host or API key to
  configure before your first invitation can be sent. If you'd rather use
  your own email provider (your own domain's deliverability, your own
  sending limits), you can still configure one exactly as a self-hosted
  install would, from **Admin → System Settings → Email delivery**.
* **AI features.** Managed AI can be turned on for your workspace without
  bringing your own OpenAI/Anthropic/Ollama key - the platform provides
  one. If you'd rather use your own provider account (your own usage
  billing, your own model choice), bring-your-own-key remains fully
  supported, configured the same way as self-hosted.
* **Scaling and database tuning.** Self-hosting exposes knobs like the
  number of API worker processes and Postgres memory settings so you can
  size an instance to your own hardware (see
  [Scaling beyond one process](/self-hosting/docker#scaling-beyond-one-process-optional)).
  On cloud, none of that exists as a setting - the platform sizes and
  scales your workspace's resources for you as usage grows.

## What is identical to self-hosting [#what-is-identical-to-self-hosting]

| Area                       | Cloud                                                  | Self-hosted                                            |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| Features, permissions, API | Same product, same behaviour                           | Same product, same behaviour                           |
| Data ownership             | Full backup export, per-user data export, GDPR tooling | Full backup export, per-user data export, GDPR tooling |
| Email providers            | Managed by default, or bring your own                  | You configure a provider yourself                      |
| AI features                | Managed key available, or bring your own               | Bring your own provider key                            |
| Admin surface              | Same admin panel and settings                          | Same admin panel and settings                          |

Everything in the [user guide](/user-guide) and
[admin guide](/admin) applies to cloud and self-hosted alike, down to
individual permission slugs and API endpoints - there is no cloud-only or
self-host-only feature gate on anything documented there. Where a page
differs by edition it says so inline; a handful of operator-facing pages -
running Docker, choosing a reverse proxy, tuning Postgres - only apply to
self-hosting, because cloud simply has no equivalent step for you to take.

## Your data [#your-data]

Your workspace's data is yours: full backup export, per-user data export
and the GDPR tooling are available in cloud exactly as in self-hosted
installations. Nothing about switching to cloud changes what you can
export or delete, or locks anything behind a migration process - the same
backup archive format that restores a self-hosted instance is what you'd
take with you if you ever moved off cloud.

## Troubleshooting [#troubleshooting]

**I can't find where to configure the server, domain, or database.**
Cause: those are exactly the pieces cloud manages for you - there is no
equivalent setting to look for, by design.
Fix: if you need infrastructure-level control (a private network, a
specific region, custom scaling), that is a self-hosting decision - see
[Self-hosting](/self-hosting). Everything else - projects, users,
integrations, AI, notifications - is configured from the same **Admin**
area cloud and self-hosted share.

**I want an on-demand backup, not just the automatic platform one.**
Cause: the automatic platform backup runs on its own schedule and isn't
something you trigger yourself.
Fix: trigger and download your own export any time from
[Admin → Backup](/admin/operations/backup) - available identically on
cloud and self-hosted, and independent of the platform's own backups.

**I want to stop using cloud and run this myself instead.**
Cause: not a limitation - just a decision to make once.
Fix: export a full backup archive from Admin → Backup, then follow
[Self-hosting with Docker](/self-hosting/docker) and restore that
archive during first-run setup on your own instance.


# Calendar sync (/integrations/calendar-sync)



orboto offers two independent ways to connect a calendar: a read-only
**feed** anyone can subscribe to in seconds, and a deeper **provider
sync** that pushes your approved absences out and pulls your busy time
in. You can use either on its own, or both together.

## Calendar feed (any calendar app) [#calendar-feed-any-calendar-app]

The feed is the fastest way to see orboto dates in a calendar you
already use - no OAuth, no admin setup.

1. Open your **profile**.
2. Find **Calendar feed** and select **Generate feed URL** (or copy the
   existing one if you already generated it).
3. Choose which schedule types the feed carries - due dates, milestones,
   absences.
4. Copy the URL and add it as a **subscription** (not an import) in your
   calendar app - the exact menu differs per app, but it's the option
   labeled "Subscribe from URL", "Add calendar by URL", or similar,
   never "Import" (import is a one-time snapshot; subscribe keeps
   refreshing).

{/* screenshot: the profile page's calendar feed card with the generated URL and type checkboxes */}

The URL contains a private, unguessable token - anyone who has the URL
can read the events it carries, so treat it like a password. If a URL
leaks (pasted somewhere public, shared with the wrong person), select
**Regenerate** - the old URL stops working immediately and every
subscriber needs the new one.

The feed is **read-only** at the consuming end: your calendar app
refreshes it periodically (the interval is controlled by the app, not
orboto - most refresh every few hours) but you can't edit an orboto
event from inside your calendar app and have it write back.

## Provider sync (Google, Microsoft 365, CalDAV) [#provider-sync-google-microsoft-365-caldav]

Provider sync is two-way in a specific sense:

* **Push** - your *approved* absences become all-day events on a
  calendar you choose (your primary/default calendar unless you pick a
  different target).
* **Pull** - your busy windows from that external calendar appear as a
  read-only hatched overlay on your **Time Calendar**, so you can plan
  orboto work against your real availability. orboto only ever reads
  *busy/free* status, never event titles or details - this is a
  deliberate privacy choice, not a current limitation.

{/* screenshot: the Time Calendar with the hatched busy-time overlay next to orboto events */}

Three providers are supported, each connected the same way from
**Profile → Connected calendars**, but set up differently underneath.

### Google Calendar [#google-calendar]

**One-time workspace setup (operator).** Before any user can connect
Google Calendar, an operator registers one OAuth client in the Google
Cloud Console that every user connects through:

1. Open the [Google Cloud Console](https://console.cloud.google.com/)
   and pick (or create) a project.
2. **APIs & Services → Library** → enable the **Google Calendar API**.
3. **APIs & Services → OAuth consent screen** → configure it (External
   or Internal - Internal is simplest if every orboto user is in the
   same Google Workspace organization).
4. **APIs & Services → Credentials → Create credentials → OAuth client
   ID** → application type **Web application**.
5. Under **Authorized redirect URIs**, add exactly:

   ```
   https://<your-orboto-host>/calendar/callback/google
   ```

   Use the exact host your workspace serves on. Add one entry per host
   if you run more than one (e.g. staging and production).
6. Set the resulting **Client ID** and **Client secret** as environment
   variables on the orboto deployment:

   ```
   GOOGLE_CALENDAR_CLIENT_ID=...
   GOOGLE_CALENDAR_CLIENT_SECRET=...
   ```

Until both are set, **Google Calendar** simply doesn't appear in the
"+ Connect" list on any user's profile - there's nothing to misconfigure
partway.

**Why two scopes.** The connection requests
`https://www.googleapis.com/auth/calendar.events` (to push - insert,
update, delete the absence events orboto owns) and
`https://www.googleapis.com/auth/calendar.readonly` (to list your
calendars for the target picker, and to read free/busy for the overlay).
The write scope alone can't enumerate calendars or query free/busy, so
the read scope is added on top - it's additive, not a downgrade.

**Per-user connect flow:**

1. **Profile → Connected calendars → Connect Google Calendar.**
2. Your browser is sent to Google's consent screen.
3. Approve access. Google redirects back to orboto.
4. orboto stores the connection (encrypted) and runs an initial sync:
   your currently-approved absences get pushed, and the busy overlay
   fills in on the next scheduled pull.
5. Back on your profile, pick a **target calendar** (defaults to your
   primary one) and toggle **push** / **pull** independently - you can
   run either direction alone if you only want one.

**Keeping the connection alive.** Google issues short-lived access
tokens (about an hour); orboto refreshes them automatically ahead of
expiry using the refresh token from your original consent - you never
see this happen. If you **revoke orboto's access from your Google
account**, or Google otherwise invalidates the grant, the *next* sync
attempt fails, the connection is marked inactive, and you get a
notification asking you to reconnect. Reconnecting just repeats the
connect flow above.

**If two edits collide.** If you (or Google Calendar) also edit one of
the events orboto pushed, the next sync overwrites your external edit
with orboto's version - orboto is authoritative for what it pushed. This
only applies to events orboto created; anything else on your calendar is
untouched.

### Microsoft 365 / Outlook [#microsoft-365--outlook]

**One-time workspace setup (operator).** Register one Microsoft Entra ID
(Azure AD) app that every user connects through:

1. Open the [Azure portal](https://portal.azure.com/) →
   **Microsoft Entra ID → App registrations → New registration**.

2. Name it (e.g. "orboto calendar sync").

3. Choose **Supported account types** - this decides single-tenant vs
   multi-tenant (see below):
   * *Accounts in this organizational directory only* → single-tenant.
   * *Accounts in any organizational directory* (optionally *and
     personal Microsoft accounts*) → multi-tenant.

4. Under **Redirect URI**, pick platform **Web** and add exactly:

   ```
   https://<your-orboto-host>/calendar/callback/microsoft
   ```

5. **API permissions → Add a permission → Microsoft Graph → Delegated
   permissions*&#x2A; → add &#x2A;*`Calendars.ReadWrite`*&#x2A; and
   &#x2A;*`offline_access`**. Grant admin consent if your tenant requires it.

6. **Certificates & secrets → New client secret** → copy the secret
   **value** immediately (Azure only shows it once).

7. Set these as environment variables on the orboto deployment:

   ```
   MICROSOFT_CALENDAR_CLIENT_ID=...
   MICROSOFT_CALENDAR_CLIENT_SECRET=...
   MICROSOFT_CALENDAR_TENANT=common
   ```

   Use `common` for multi-tenant (any work/school account across any
   Entra tenant can connect - the broadest reach, but a foreign tenant's
   admin may need to consent separately). Use your directory (tenant) id
   instead for single-tenant (only your own organization's accounts can
   connect - the tightest scope, and the right default when every
   orboto user is in the same Microsoft org).

Until the client id and secret are set, **Microsoft 365** doesn't appear
in the "+ Connect" list.

**Why one scope covers both directions.** Unlike Google, `Calendars.ReadWrite`
alone covers push AND the reads needed for the calendar picker and the
busy overlay - so Microsoft's scope set stays to just that plus
`offline_access` (needed to get a refresh token, since access tokens
only last about an hour).

**Per-user connect flow:**

1. **Profile → Connected calendars → Connect Microsoft 365.**
2. Consent on Microsoft's page.
3. orboto stores the connection and runs an initial sync.
4. Pick a **target calendar** (defaults to your default calendar) and
   toggle push / pull.

**Keeping the connection alive.** orboto refreshes access tokens
proactively before they expire, and Microsoft rotates the refresh token
on every refresh - orboto always re-stores the newest one, so this
requires no attention from you. If Microsoft's API is temporarily
rate-limiting requests, orboto waits and retries automatically; you'd
only notice as a slightly delayed sync, never a failure. As with Google,
if you revoke access or the grant otherwise becomes invalid, the next
sync fails, the connection is marked inactive, and you're notified to
reconnect.

**If two edits collide,** the same rule as Google applies: orboto is
authoritative for events it pushed, and overwrites external edits to
those specific events on the next sync.

### CalDAV (self-hosted / other providers) [#caldav-self-hosted--other-providers]

CalDAV is the option for any RFC-4791 server - Nextcloud, Mailcow,
Fastmail, Posteo, mailbox.org, Apple iCloud, and more - and needs **no
workspace setup**. It always appears under "+ Connect" because there's
no OAuth app to register first; you connect directly with a server URL
and credentials.

**Per-user connect flow:**

1. **Profile → Connected calendars → CalDAV.**
2. Fill in:
   * **Server URL** - the CalDAV entry point for your provider (see the
     per-provider values below). A quick-preset chip row prefills the
     common ones.
   * **Username** - usually your email address or account login.
   * **Password** - for any account with two-factor authentication
     (iCloud, Fastmail, many mailbox providers) this **must** be an
     app-specific password, not your normal login password; your
     regular password will be rejected by the provider itself.
3. orboto verifies the credentials against the server before saving
   anything - a wrong URL or password fails immediately with a clear
   error, nothing partial gets stored. On success it lists your
   calendars and pre-selects the primary one as the sync target; change
   the target any time from the account card.

**Per-provider server URL and password notes:**

| Provider                                                | Server URL                                                                                                                              | Password                                                                                                                                                                             |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nextcloud / ownCloud                                    | `https://<your-host>/remote.php/dav`                                                                                                    | Your login password, or an app password from **Security → Devices & sessions** if 2FA is on.                                                                                         |
| Fastmail                                                | `https://caldav.fastmail.com`                                                                                                           | An app password from **Settings → Privacy & Security → App passwords**, scoped to CalDAV - your normal password won't work.                                                          |
| Apple iCloud                                            | `https://caldav.icloud.com`                                                                                                             | An app-specific password from [account.apple.com](https://account.apple.com) → Sign-In & Security → App-Specific Passwords. iCloud rejects your plain Apple ID password over CalDAV. |
| Mailcow (SOGo)                                          | typically `https://<host>/SOGo/dav`                                                                                                     | An app password where the provider offers one.                                                                                                                                       |
| Posteo, mailbox.org, and other generic RFC-4791 servers | the provider's published CalDAV endpoint (or your account's direct calendar URL if that's all you have - discovery degrades gracefully) | An app password where the provider offers one.                                                                                                                                       |

**Sync timing.** Push is event-driven: approving, updating, or
cancelling an absence sends the change to your calendar within moments.
Pull runs on a schedule (about every 15 minutes) and covers the next 30
days of busy time; if nothing changed on your calendar since the last
pull, orboto reuses the cached result instead of re-fetching, so an
unchanged calendar doesn't cost extra requests.

**If the server later rejects your stored credentials** (password
rotated, app password revoked), the next sync marks the account
**Reconnect** and notifies you. Re-enter the credentials from the
account card to resume - nothing else about the connection changes.

**Self-hosted note.** If your CalDAV server lives on a private network
address (e.g. a LAN Nextcloud instance), the operator needs to set
`WEBHOOK_ALLOW_PRIVATE_IPS=true` on the orboto deployment - by default,
outbound requests to loopback/private/link-local addresses are blocked
as an SSRF guard. This setting affects every outbound user-supplied URL
on the instance (webhooks included), so only enable it when the orboto
instance itself runs inside a trusted network.

## Invitations [#invitations]

Scheduled items that involve other people (for example, planning
sessions) go out as standard calendar invitations attached to the
notification email - accepting one adds it to whatever calendar app you
open the invitation with, independent of the feed and provider-sync
paths above.

## Troubleshooting [#troubleshooting]

| Symptom                                                     | Fix                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The feed shows nothing / stopped updating                   | Confirm you subscribed (not imported) - an import is a one-time snapshot and will never update again. Also check the feed still has schedule types selected in your profile; an empty selection carries zero events by design.                                                                                                       |
| Feed URL was pasted somewhere it shouldn't have been        | Regenerate it from your profile immediately - the old URL stops working the instant you do, cutting off whoever has it, but every legitimate subscriber (including your own devices) needs to re-subscribe with the new one.                                                                                                         |
| A provider doesn't appear in "+ Connect"                    | For Google or Microsoft 365, this means the workspace-level OAuth app hasn't been registered yet - that's an operator task (see the setup steps above), not something a user can self-serve. CalDAV always appears; if it doesn't, something's wrong with the instance itself.                                                       |
| Connection shows "Reconnect"                                | The stored credentials or token grant stopped working - most often you (or your IT) revoked access on the provider's side, a password rotated, or an app password was regenerated. Reconnect using the same steps as the initial connect.                                                                                            |
| Busy overlay is empty even though the connection is active  | Pull runs on its own schedule (roughly every 15 minutes for CalDAV; Google/Microsoft similarly poll rather than push instantly) - give it a few minutes after connecting. If it's still empty after that, check the connected calendar actually has events in the next 30 days, and that **pull** is toggled on for that connection. |
| An event orboto pushed keeps reverting your manual edit     | Expected behavior - orboto is authoritative for events it created and overwrites external edits to them on the next sync. Edit the absence in orboto instead of the calendar event directly.                                                                                                                                         |
| CalDAV connect fails against a server on your local network | If the CalDAV server is on a private/LAN address, ask your operator whether `WEBHOOK_ALLOW_PRIVATE_IPS` is enabled - by default the SSRF guard blocks private-network destinations.                                                                                                                                                  |


# Chat and webhook notifications (/integrations/chat-notifications)



Beyond in-app and email, every user can route their own notifications to
an external channel: **Discord**, **Slack**, **Microsoft Teams**,
**Telegram**, or a **custom webhook** to any HTTPS endpoint. Channels are
per-user - each person connects their own, and picks which notification
types go to which channel (for example, only mentions and assignments to
chat, everything else staying in-app).

## Connecting a channel [#connecting-a-channel]

Open **notification settings** (gear icon in the top bar) and add a
channel of the type you want.

### Discord [#discord]

1. In your Discord server: **Server Settings → Integrations → Webhooks →
   New Webhook**.
2. Copy the webhook URL and paste it into the channel form.

### Slack [#slack]

1. In your Slack workspace: **Apps → Incoming Webhooks**.
2. Add the integration to the channel you want notifications posted in.
3. Copy the generated webhook URL and paste it into the channel form.

### Microsoft Teams [#microsoft-teams]

1. In the target Teams channel: **⋯ → Connectors → Incoming Webhook →
   Configure**.
2. Name the connector (e.g. "orboto") and optionally upload an icon,
   then **Create**.
3. Copy the webhook URL and paste it into the channel form.

### Telegram [#telegram]

Telegram needs one piece of workspace-level setup before any user can
connect it:

1. **Workspace admin, one-time**: create a bot via
   [BotFather](https://t.me/BotFather) and set the resulting bot token
   under **Admin → System settings → Telegram bot token**. This enables
   Telegram as a channel type for the whole workspace.
2. **Each user**: start a chat with the workspace's bot and send
   `/start` - it replies with your chat ID. Paste that chat ID into your
   notification settings.

### Custom webhook [#custom-webhook]

Point notifications at any HTTPS endpoint - useful for Zapier, n8n,
Make, Power Automate, or a bot you run yourself. Each notification
arrives as a JSON POST.

* **Shared secret** (optional) - when set, every request carries an
  `X-Orboto-Signature: sha256=<hmac>` header so your endpoint can verify
  it actually came from orboto.
* **Custom headers** - up to 5 extra HTTP headers on every request.
  Reserved keys (`Authorization`, `X-Orboto-Signature`, `User-Agent`,
  `Content-Type`) are stripped server-side, so a header you set can't
  collide with orboto's own.

{/* screenshot: the add-channel form with the type picker (Discord/Slack/Teams/Telegram/webhook) */}

## Verify the channel [#verify-the-channel]

After saving, select **Verify** to send a test message. A channel stays
**unverified** - and is excluded from delivery, even with its per-event
toggle on - until it successfully receives that test. This catches a
mistyped URL or an unconfirmed Telegram chat ID before it costs you a
missed notification later.

Once verified, pick which notification types go to which channel - see
[Notifications](/user-guide/everyday/notifications) for the full
per-event routing and the notification inbox itself.

## Behavior [#behavior]

Delivery is fire-and-forget: a failing channel never blocks orboto, and
every attempt lands in a delivery log so you (or an administrator) can
diagnose a silent channel.

## Troubleshooting [#troubleshooting]

| Symptom                                                                     | Fix                                                                                                                                                                                                                          |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A channel never receives anything                                           | Check its status first - an **unverified** channel is excluded from delivery even if its per-event toggle is on. Select **Verify** again.                                                                                    |
| Discord/Slack/Teams channel stopped working after previously verifying fine | The integration was likely deleted or regenerated on that platform's side - all three let you remove or reissue a webhook independently of orboto, which silently breaks delivery until you paste the new URL and re-verify. |
| Telegram option doesn't appear in the channel type picker                   | An admin hasn't set the workspace's Telegram bot token yet (**Admin → System settings**) - Telegram only shows up as a choice once that's configured.                                                                        |
| Telegram messages don't arrive despite a valid chat ID                      | Send `/start` to the bot again from the account you expect notifications on - chat IDs are per Telegram account, and a chat that never messaged the bot can't receive a push from it.                                        |
| Custom webhook signature doesn't verify                                     | Compute the HMAC over the **raw** request body using the shared secret you set, not a re-serialized copy of the parsed JSON.                                                                                                 |


# Integrations (/integrations)



orboto connects to the tools around it - AI clients, code repositories, chat tools, and email. Some connections you set up yourself; the workspace-wide ones are handled by an administrator. This chapter covers the parts you touch as a regular user, and points you to the admin material for the rest.

## Connecting an AI client to your workspace [#connecting-an-ai-client-to-your-workspace]

You can connect an AI client - such as Claude Desktop, Cursor, or a Copilot-style assistant in your editor - to orboto, so it can read and update your tickets and docs directly from that tool. orboto speaks the **Model Context Protocol** (MCP), the standard these clients use to talk to external systems.

The usual flow:

1. In your AI client, add orboto as an MCP connection using the address your workspace provides.
2. Your browser opens an orboto **consent screen** asking you to approve the connection for your account.
3. The consent screen also lets you choose **which identity the connection acts as** - yourself (the default: every ticket, comment, and timer the client touches is attributed to you, with your exact permissions), or an AI agent account you own, if your workspace uses those. Choosing an agent account keeps your own personal timer and timesheet untouched, since the connection's actions are attributed to the agent instead.
4. Review what it will be allowed to do and **approve**. The client is now connected and acts with the chosen identity's permissions - it can never see or change more than that account can.

{/* screenshot: the AI-client connection consent screen with the identity picker */}

If you decline, or close the browser tab without approving, nothing is connected - the client simply reports it couldn't authorize, and no partial access is granted. You can revisit and approve later from the same "add connection" step in your client.

**Revoking access later.** Open **Profile → Connected AI clients** to see every client that's ever connected, when it last used the connection, and which identity it's acting as. Remove one you no longer use, or one you don't recognize, and its access ends immediately - the next call that client makes fails authentication rather than silently keeping working.

{/* screenshot: the Connected AI clients list on the Profile page */}

Anything the connected client does respects your roles and access exactly as if you did it in the app. For the detailed setup steps per client, see the [MCP setup guide](/agents-ai/mcp).

## Chat notifications [#chat-notifications]

To send orboto notifications into Discord, Slack, Microsoft Teams, Telegram, or a custom webhook, set up a channel in **Notification settings** - see [Chat and webhook notifications](/integrations/chat-notifications) for the exact connection steps per platform, and [Notifications](/user-guide/everyday/notifications) for routing individual event types to a channel.

## Code repositories (Git) [#code-repositories-git]

When your workspace is connected to a code host (such as GitHub or GitLab), mentioning a ticket key in a commit message or pull request links that work to the ticket automatically. You then see linked commits and pull requests on the ticket's **Git** tab (see [Projects and tickets](/user-guide/work/projects-and-tickets)).

Connecting the repository itself is an administrator task - see the [administration](#administration-topics) pointers below.

## Administration topics [#administration-topics]

The following are set up and run by workspace administrators, not individual users. They are documented separately; the most relevant references already in this repository are linked here:

* **Inviting and managing users, roles, and permissions** - the admin area.
* **Single sign-on (SSO)** - [sso-setup.md](/admin/identity/sso).
* **Automatic user provisioning (SCIM)** - connect your identity provider so joiners and leavers sync automatically (setup guide coming to this section).
* **Importing from another tool** (issues, projects, CSV) - the admin import area.
* **Backups and restore** - [backup-destinations.md](/self-hosting/backups).
* **Inbound email to tickets** - [inbound-email.md](/admin/email/inbound-email).
* **The MCP server and AI provider configuration** - [mcp-setup.md](/agents-ai/mcp) and the admin AI settings.
* **Webhooks, API keys, audit log, compliance export, and federation** - the admin area.

If you need any of these enabled or changed, contact a workspace administrator.


# n8n operation reference (/integrations/n8n-reference)



This page is the complete field-by-field reference for the
[`n8n-nodes-orboto`](/integrations/n8n) package: every operation on the
**orboto** action node, grouped by resource, and every event the **orboto
Trigger** node can fire on. For installation, credentials, error-handling
semantics (422/409/423/429), and a worked walkthrough, see
[n8n](/integrations/n8n) first - this page assumes you've already
connected a credential and just need to know what a specific operation
expects.

A few conventions that apply across every resource below:

* **"Project"** fields are dropdowns that load your orboto projects live -
  you rarely need to type a key or ID by hand.
* **"Ticket"** fields accept a ticket **key** (`ACME-42`), a bare **number**
  (`42`, resolved against the Project field), or a **UUID** - whichever is
  most convenient in your workflow.
* Fields marked &#x2A;(loaded live)* are dropdowns populated from your connected
  orboto instance (statuses, members, labels, milestones, versions, doc
  spaces) rather than typed by hand.
* A field left blank on **Update**-style operations is left untouched on the
  ticket/milestone/doc - see [n8n](/integrations/n8n) for the general
  error-handling and rate-limit notes that apply to every operation.

## Ticket [#ticket]

| Operation                             | Required fields                                 | Optional fields                                                                                                                                                                                                                                                                                                                                                                                   | Notes                                                                                                                                                                                                                   |
| ------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create                                | Project, Title                                  | Description, Type, Priority, Status &#x2A;(loaded live)&#x2A;, Milestone &#x2A;(loaded live)&#x2A;, Version &#x2A;(loaded live)&#x2A;, Label Names &#x2A;(loaded live, multi)*, Assignee Emails (comma-separated), Parent Ticket, Start Date, Due Date, Estimated Time (minutes), Private, Delivery Mode, Skip Auto-Translate, Allow Language Mismatch, Allow Duplicate + Duplicate Justification | Type: `epic`/`story`/`task`/`bug`. Priority: `blocker`/`high`/`normal`/`low`/`trivial`. Delivery Mode: `implementation`/`docs`/`review`/`admin`/`epic`. Duplicate Justification is required when Allow Duplicate is on. |
| Get                                   | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Get Many                              | Project                                         | Return All / Limit, Status Category, Assignee &#x2A;(loaded live)&#x2A;, Milestone Filter &#x2A;(loaded live)*, Parent Ticket Filter, Search, Include Closed Milestones                                                                                                                                                                                                                           | Status Category: `todo`/`in_progress`/`in_review`/`done`/`wont_fix`.                                                                                                                                                    |
| Update                                | Project, Ticket                                 | Update Fields collection: Description, Type, Priority, Status, Milestone, Version, Start Date, Due Date, Estimated Time, Private, Delivery Mode, Skip Auto-Translate, Label Names, Assignee Emails, Parent Ticket; Allow Language Mismatch                                                                                                                                                        | Only fields explicitly added to the Update Fields collection are changed - everything else on the ticket is left alone.                                                                                                 |
| Delete                                | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 | Permanent unless the ticket is under legal hold (423). Prefer moving to `wont_fix` over deleting when in doubt.                                                                                                         |
| Move (Change Status)                  | Project, Ticket, Status &#x2A;(loaded live)*    | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Assign / Unassign                     | Project, Ticket, User &#x2A;(loaded live)*      | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Comment                               | Project, Ticket, Comment                        | Internal                                                                                                                                                                                                                                                                                                                                                                                          | Comment body is Markdown. Internal comments aren't visible to customers.                                                                                                                                                |
| Log Time                              | Project, Ticket, Duration (minutes)             | Time Description, Logged At                                                                                                                                                                                                                                                                                                                                                                       | Logged At defaults to now.                                                                                                                                                                                              |
| Add Label / Remove Label              | Project, Ticket, Label &#x2A;(loaded live)*     | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| OQL Query                             | Query, Syntax                                   | Return All / Limit                                                                                                                                                                                                                                                                                                                                                                                | Syntax: `oql` or `jql`. No Project field - the query itself scopes the results. Paginates automatically via cursor until Limit (or all results, with Return All) is reached.                                            |
| Set Milestone                         | Project, Ticket, Milestone &#x2A;(loaded live)* | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Clear Milestone                       | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Set Version                           | Project, Ticket, Version &#x2A;(loaded live)*   | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Clear Version                         | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Add Dependency / Remove Dependency    | Project, Ticket, Depends On Ticket              | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Get Dependencies                      | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Checklists: Add Item                  | Project, Ticket, Checklist ID, Item Text        | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Checklists: Check Item / Uncheck Item | Project, Ticket, Item ID                        | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Get Attachments                       | Project, Ticket                                 | -                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                         |
| Add Attachment                        | Project, Ticket, Binary Property                | -                                                                                                                                                                                                                                                                                                                                                                                                 | Binary Property names the input item's binary field holding the file (default `data`).                                                                                                                                  |
| Bulk Update                           | Project, Ticket IDs (comma-separated), Action   | Value, shaped per Action                                                                                                                                                                                                                                                                                                                                                                          | Action: `status` / `milestone` / `assignee` / `version` / `priority` / `due_date`, each with its own live-loaded or plain Value field. Prefer this over looping per-ticket updates for large batches.                   |

## Milestone [#milestone]

| Operation | Required fields                | Optional fields                                                                                                     |
| --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Create    | Project, Name                  | Milestone Key, Start Date, End Date, Budget Amount, Budget Hours, Private                                           |
| Get       | Project, Milestone (key or ID) | -                                                                                                                   |
| Get Many  | Project                        | Include Closed                                                                                                      |
| Update    | Project, Milestone             | Milestone Key, Start Date, End Date, Status (`active`/`completed`/`archived`), Budget Amount, Budget Hours, Private |
| Close     | Project, Milestone             | -                                                                                                                   |

Close is a convenience wrapper around Update with Status set to
`completed`.

## Project [#project]

| Operation        | Required fields     | Optional fields                                                                 |
| ---------------- | ------------------- | ------------------------------------------------------------------------------- |
| Create           | Name                | Key, Description, Language                                                      |
| Get              | Project (key or ID) | -                                                                               |
| Get Many         | -                   | -                                                                               |
| Update           | Project             | Name, Key, Description, Language, Status (`draft`/`active`/`archived`/`closed`) |
| Get Primer Facts | Project             | -                                                                               |
| Get AI Primer    | Project             | -                                                                               |

Key must be 2-10 uppercase characters (letters and digits). Language is the
ticket language enforced for that project - see [n8n](/integrations/n8n)
for how the node surfaces a language mismatch.

## Doc [#doc]

| Operation      | Required fields                   | Optional fields            | Notes                                                                                                      |
| -------------- | --------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Create         | Space &#x2A;(loaded live)*, Title | Content, Visibility        | Visibility: `public`/`workspace`/`members`/`specific`, default `workspace`.                                |
| Get            | Doc (key or ID)                   | -                          |                                                                                                            |
| Get Many       | Space                             | -                          |                                                                                                            |
| Update         | Doc                               | Title, Content, Visibility | Only the fields set are changed.                                                                           |
| Ask Docs (RAG) | Question                          | Limit Results              | Requires an embedding provider configured on the instance - a clear error explains this if none is set up. |
| Ingest URL     | Space, URL                        | Raw HTML                   | Pass Raw HTML to ingest pre-fetched content instead of letting orboto fetch the URL itself.                |

## Time Entry [#time-entry]

| Operation | Required fields                               | Optional fields        |
| --------- | --------------------------------------------- | ---------------------- |
| Log       | Project, Ticket, Duration (minutes)           | Description, Logged At |
| Get Many  | Project, Ticket                               | -                      |
| Edit      | Project, Ticket, Entry ID, Duration (minutes) | Description            |
| Delete    | Project, Ticket, Entry ID                     | -                      |

All time-entry operations are ticket-scoped.

## User [#user]

| Operation           | Required fields |
| ------------------- | --------------- |
| Get Project Members | Project         |

There's no global user directory operation - member reads are always scoped
to one project, matching the fact that orboto has no workspace-wide "all
users" list a non-admin can read.

## Label [#label]

| Operation | Required fields | Optional fields |
| --------- | --------------- | --------------- |
| Create    | Project, Name   | Color           |
| Get Many  | Project         | -               |

## Saved Search [#saved-search]

| Operation | Required fields           | Optional fields                               | Notes                                                                                                                                                          |
| --------- | ------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create    | Name, Query Type          | OQL Query (when Query Type is `oql` or `jql`) | Query Type: `oql`/`jql`/`legacy`.                                                                                                                              |
| Get Many  | -                         | -                                             |                                                                                                                                                                |
| Run       | Saved Search (name or ID) | -                                             | Only OQL/JQL saved searches can be run from n8n - a `legacy`-type saved search fails with a clear error, since legacy queries have no OQL/JQL text to execute. |

## Agent [#agent]

The n8n-to-agent bridge - lets a workflow talk to an [agent
identity](/agents-ai/work-routing)'s inbox the same way one agent
notifies another.

| Operation    | Required fields               | Optional fields                                                    | Notes                                                                                                                                                               |
| ------------ | ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Notify       | Target Email, Subject         | Kind, Payload (JSON), Thread ID, Project Scope, Sender Reference   | Kind: `info` (FYI), `request` (expects an answer), `complete` (closes a request), `error` (reports failure). Project Scope routes the message to the right session. |
| Get Messages | -                             | Include Already-Delivered, Limit, Exclude Reference, Project Scope | By default returns only messages not yet delivered to this reader.                                                                                                  |
| Ack Messages | Message IDs (comma-separated) | -                                                                  | Marks messages as delivered so a later Get Messages call doesn't return them again.                                                                                 |

## orboto Trigger: events [#orboto-trigger-events]

The trigger's **Events** field lists these 16 events; check any combination.
An **Additional Events** free-text field (comma-separated) lets you subscribe
to event types added to orboto after this package version shipped, before
the node has a dedicated checkbox for them.

| Event                             | Fires when                                                                                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket.created`                  | A ticket is created.                                                                                                                                      |
| `ticket.updated`                  | A ticket's fields change.                                                                                                                                 |
| `ticket.deleted`                  | A ticket is deleted.                                                                                                                                      |
| `ticket.ready`                    | A ticket becomes unblocked (its dependencies are resolved).                                                                                               |
| `ticket.checklist_item.completed` | A checklist item on a ticket is checked.                                                                                                                  |
| `comment.created`                 | A comment is posted.                                                                                                                                      |
| `comment.updated`                 | A comment is edited.                                                                                                                                      |
| `comment.deleted`                 | A comment is deleted.                                                                                                                                     |
| `project.member_added`            | A member joins a project.                                                                                                                                 |
| `project.member_removed`          | A member leaves a project.                                                                                                                                |
| `milestone.created`               | A milestone is created.                                                                                                                                   |
| `milestone.updated`               | A milestone's fields change.                                                                                                                              |
| `version.released`                | A version is marked released.                                                                                                                             |
| `symphony.candidates_changed`     | A ticket's status, assignee, or priority changes, in a shape relevant to a [Symphony](/integrations/symphony) coding-agent orchestrator polling for work. |
| `inbound.signal.received`         | An inbound signal (e.g. from inbound email processing) is received.                                                                                       |
| `agent.escalation_raised`         | An AI agent raises an escalation that needs human attention.                                                                                              |

Every delivery is scoped to the **Project** you selected on the trigger
node - webhooks in orboto are project-scoped, so one trigger node watches
one project. Add a second orboto Trigger node for a second project.


# n8n (/integrations/n8n)



`n8n-nodes-orboto` is the official community node for the n8n workflow
platform. It brings two nodes:

* **orboto** (action node): tickets, milestones, projects, docs, time
  entries, labels, saved searches, and agent messaging.
* **orboto Trigger**: fires your workflow on workspace events, delivered
  as HMAC-verified webhooks.

## Install [#install]

In n8n: **Settings → Community nodes → Install** and enter
`n8n-nodes-orboto`.

Self-hosted n8n can also install it manually into the user folder and
restart:

```bash
cd ~/.n8n/custom
npm install n8n-nodes-orboto
```

Community nodes are enabled by default on both n8n Cloud and self-hosted
instances.

## Credentials [#credentials]

Two credential types, both accepting a self-hosted base URL (either
`https://orboto.example.com` or `https://orboto.example.com/api` work):

* **orboto API** (simplest) - an API key from orboto (**Profile → API
  keys**, or an admin-issued bot key) plus your instance base URL. Use a
  dedicated [bot identity](/admin/identity/users-and-roles) per
  workflow so activity stays attributable and revocable. The credential
  test performs an authenticated read for immediate feedback.
* **orboto OAuth2 API** - for instances with OAuth enabled. An
  administrator creates a static OAuth client under **Admin → OAuth
  clients** in orboto; paste its client id (and secret, if confidential)
  into the credential. The flow is PKCE with the `api offline_access`
  scope, so tokens refresh automatically, and the authorize/token URLs
  are discovered from the base URL.

{/* screenshot: the orboto credential setup form in n8n */}

## The orboto node [#the-orboto-node]

Action node covering the orboto REST API, organized by resource:

| Resource     | Operations                                                                                                                                                                                                                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Ticket       | Create, Get, Get Many (filters, Return All/Limit), Update, Delete, Move (change status), Assign, Unassign, Comment, Log Time, Add Label, Remove Label, OQL Query, Set/Clear Milestone, Set/Clear Version, Dependencies (Add/Remove/Get), Checklists (Add Item, Check, Uncheck), Attachments (Add, Get Many), Bulk Update |
| Milestone    | Create, Get, Get Many, Update, Close                                                                                                                                                                                                                                                                                     |
| Project      | Create, Get, Get Many, Update, Get Primer Facts, Get AI Primer                                                                                                                                                                                                                                                           |
| Doc          | Create, Get, Get Many, Update, Ask Docs (RAG), Ingest URL                                                                                                                                                                                                                                                                |
| Time Entry   | Log, Get Many, Edit, Delete (ticket-scoped)                                                                                                                                                                                                                                                                              |
| User         | Get Project Members                                                                                                                                                                                                                                                                                                      |
| Label        | Create, Get Many                                                                                                                                                                                                                                                                                                         |
| Saved Search | Create, Get Many, Run (OQL/JQL)                                                                                                                                                                                                                                                                                          |
| Agent        | Notify, Get Messages, Ack Messages - the n8n-to-agent bridge                                                                                                                                                                                                                                                             |

Ticket references accept a key (`ACME-42`), a number (`42`), or a UUID
anywhere the node asks for one. Dropdowns for project, milestone,
status, member, label, version, and doc space load live from your
connected instance instead of requiring you to paste ids.

**Rate limit**: 600 requests/minute per instance. For large batches,
prefer the bulk-update operation over looping per-ticket updates, and
turn on **Continue On Fail** so one bad row doesn't stop the whole run.

**Error handling as first-class options**, not opaque failures:

* **422 language enforcement** - enable *Allow Language Mismatch* to
  create/update anyway; the response carries a `languageWarning`.
* **409 duplicate block** - enable *Allow Duplicate* plus a required
  justification; `similarWarnings` land in the node output so the
  workflow can branch on them.
* **423 legal hold** (delete) and **429 rate limit** - both documented
  on the relevant operation, with the retry guidance you'd expect.

## The orboto Trigger node [#the-orboto-trigger-node]

Fires your workflow on orboto events over the webhook system:

* **Auto-registers** a project-scoped webhook when you **activate** the
  workflow, and removes it when you **deactivate** it - no manual
  webhook setup in orboto.
* Every delivery is verified against the `X-Orboto-Signature` header
  (HMAC-SHA256, constant-time compare); unsigned or forged requests are
  rejected before your workflow runs.
* **Events**: `ticket.created`, `ticket.updated`, `ticket.deleted`,
  `ticket.ready`, `ticket.checklist_item.completed`, `comment.created`,
  `comment.updated`, `comment.deleted`, `project.member_added`,
  `project.member_removed`, `milestone.created`, `milestone.updated`,
  `version.released`, `symphony.candidates_changed`,
  `inbound.signal.received`, `agent.escalation_raised` - plus a
  free-text field so a newer orboto version's events still work before
  the node ships a dedicated dropdown entry for them.

n8n must be reachable from your orboto instance for the webhook delivery
to land - set `WEBHOOK_URL` / `N8N_WEBHOOK_URL` if n8n runs behind a
reverse proxy.

{/* screenshot: the orboto Trigger node's event picker */}

## Walkthrough: notify a chat channel on new tickets [#walkthrough-notify-a-chat-channel-on-new-tickets]

This builds the smallest complete workflow - two nodes - so you can see
exactly how the trigger and the credential fit together before
combining them into something bigger.

1. **Create a new workflow** in n8n and add an **orboto Trigger** node
   as the starting node (n8n prompts you to pick a trigger when the
   canvas is empty).
2. On the node, select your **orboto OAuth2 API** or **orboto API**
   credential (see [Credentials](#credentials) above - create one first
   if you haven't).
3. Set **Project** - the dropdown loads your orboto projects live, so
   pick one instead of typing a key.
4. Under **Events*&#x2A;, check &#x2A;*`ticket.created`**. Leave the other events
   unchecked - each checked event adds to the same webhook registration,
   so you can always come back and add more later.
5. Add a second node - an HTTP Request node pointed at your chat tool's
   incoming webhook, or any messaging node your n8n instance has
   available. Connect it to the orboto Trigger node's output.
6. In the second node, reference the trigger's output data to build your
   message - for example `{{$json.ticket.key}}: {{$json.ticket.title}}`
   pulls the new ticket's key and title straight from the event payload.
7. **Save**, then **Activate** the workflow (the toggle in the top
   right). Activating is what actually registers the webhook in orboto -
   nothing fires while the workflow is only saved as a draft.
8. Create a test ticket in the project you selected. Within moments, the
   second node should run and your chat channel should receive the
   message.

If nothing arrives, work through the [Troubleshooting](#troubleshooting)
table below - the two most common causes are the workflow not actually
being activated, and n8n's webhook URL not being reachable from your
orboto instance.

## Example flows [#example-flows]

Beyond the walkthrough above, these are the other patterns worth
knowing about - all use the same two nodes, just wired differently:

* **Scheduled work**: a cron trigger creates a recurring ticket, labeled
  `agent:<tag>` so your [agent fleet](/agents-ai/work-routing) picks
  it up.
* **Event bridge**: orboto Trigger on `ticket.created` posts to your
  team chat.
* **Nightly digest**: a Schedule Trigger runs an OQL query and posts an
  aggregated summary - e.g. everything closed in the last 24 hours.
* **Escalation**: trigger on comments matching a keyword like "BLOCKED",
  notify a human channel.
* **Two-way sync**: orboto Trigger pushes changes outbound to an
  external system, and an inbound webhook from that system updates the
  orboto ticket back - with a loop guard so the two directions don't
  fight each other.

The package ships importable example workflows covering these patterns,
installed alongside the node.

## Troubleshooting [#troubleshooting]

| Symptom                                                       | Fix                                                                                                                                                                                                                       |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Credential test fails                                         | Confirm the base URL is reachable from wherever n8n runs (not just your browser), and that the API key hasn't been revoked. Both `https://host` and `https://host/api` are accepted - try the other form if one fails.    |
| orboto Trigger never fires                                    | Check the workflow is **activated** (the webhook only registers on activation) and that n8n's public webhook URL is reachable from your orboto instance - set `WEBHOOK_URL`/`N8N_WEBHOOK_URL` if n8n sits behind a proxy. |
| Trigger fires but the workflow shows a signature error        | The delivery's `X-Orboto-Signature` didn't match - this usually means the webhook was edited or re-created outside n8n after the trigger registered it. Deactivate and reactivate the workflow to re-register cleanly.    |
| Bulk ticket updates fail partway through                      | Enable **Continue On Fail** on the node so one bad row doesn't abort the batch, then re-run on just the failed items.                                                                                                     |
| A create/update silently returns a warning instead of failing | Check the node output for `languageWarning` or `similarWarnings` - these are the 422/409 guardrails surfacing as data rather than an error, by design; branch on them in your workflow.                                   |
| Hitting rate limits on a large sync                           | 600 requests/minute per instance - batch with the bulk-update operation, add a wait node between large loops, or split the sync across a schedule.                                                                        |


# SCIM provisioning (/integrations/scim)



SCIM keeps orboto's user list in lockstep with your identity provider
(IdP): joiners get orboto accounts automatically when IT adds them in
the IdP, leavers are deactivated the moment IT disables them there, and
profile updates (name, department, manager) flow through without anyone
touching orboto directly. It's the natural next step after
[single sign-on](/admin/identity/sso) - SSO handles logging in,
SCIM handles who exists to log in as.

SCIM is an Enterprise capability, configured entirely under
**Admin → SCIM provisioning**.

## What SCIM does, concretely [#what-scim-does-concretely]

orboto implements the standard SCIM 2.0 user-provisioning protocol
(RFC 7644), which means:

* Your IdP can **create** a new orboto user the moment someone is
  assigned the app in the IdP.
* Your IdP can **update** a user's profile fields (name, email,
  department, manager, employee number) whenever they change in the IdP
  * orboto stays a mirror, not a second source of truth.
* Your IdP can **deactivate or delete** a user the moment they're
  unassigned or offboarded - see [Deprovisioning](#deprovisioning-deactivate-vs-delete)
  for the exact difference between those two actions.
* orboto also answers the IdP's discovery calls (what resource types and
  schemas it supports) and supports the enterprise-user schema
  extension, so fields like `employeeNumber`, `department`, and
  `manager` map correctly instead of being dropped.

Group provisioning isn't available yet - user provisioning covers the
common IdP setups used today; if your IdP workflow depends on
group-based assignment specifically, confirm your rollout plan accounts
for that gap.

## Setup [#setup]

1. Under **Admin → SCIM provisioning**, enable provisioning. orboto
   shows the **SCIM endpoint URL** you'll need
   (`https://<your-host>/api/scim/v2`).
2. Select **Mint a provisioning token**. The bearer token is displayed
   **once** - copy it immediately into your IdP's configuration; if you
   navigate away before pasting it, you'll need to mint a new one (the
   plaintext is never shown again, only a masked reference).
3. In your IdP's provisioning app, set the SCIM base URL and the bearer
   token from steps 1-2. Every major IdP has a **Test connection**
   button at this stage - use it before turning anything on for real
   users.
4. **Test with a single user first.** Assign one test account in the
   IdP, confirm it appears correctly in orboto (right name, right email,
   right department if you're using the enterprise extension), then
   deactivate that same test user in the IdP and confirm it deactivates
   in orboto too. Only after both directions check out, assign the full
   group of users.

{/* screenshot: the Admin -> SCIM provisioning page with the endpoint URL and token panel */}

### Per-IdP setup [#per-idp-setup]

The general shape (base URL + bearer token) is the same everywhere; here
is exactly where each major IdP asks for it:

| Identity provider             | Where to configure it                                     | What goes in the auth field                                                 |
| ----------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- |
| Azure AD / Microsoft Entra ID | Enterprise App → Provisioning → Automatic                 | **Tenant URL** = the SCIM endpoint URL, **Secret Token** = the minted token |
| Okta                          | App → Provisioning → Integration → Enable API integration | **Base URL** = the SCIM endpoint URL, **API Token** = the minted token      |
| Google Workspace              | Apps → Web and mobile apps → Auto-provisioning            | SCIM endpoint URL + the minted bearer token                                 |
| JumpCloud                     | SSO app → Identity Management → Configure                 | Base URL + the minted bearer token                                          |

orboto is verified against the exact payload quirks of all four -
including Azure AD sending booleans as strings (`"true"` instead of
`true`) and Okta's PATCH requests that sometimes omit the `path`
attribute the spec technically expects. You don't need to work around
either; orboto's endpoint already handles them.

If your IdP isn't one of these four, any standards-compliant SCIM 2.0
client should still work - the endpoint follows RFC 7644 rather than
special-casing a fixed vendor list.

## Token rotation [#token-rotation]

Mint, rotate, and revoke tokens from **Admin → SCIM provisioning**.

* **Rotate** issues a brand-new token and keeps the **old one valid for
  a 24-hour overlap window**. This is the safe way to change tokens:
  update the IdP with the new token at your own pace within that window,
  rather than the provisioning breaking the instant you rotate.
* **Revoke** kills a token immediately, no overlap. Use this when a
  token has leaked or you're decommissioning an IdP integration for
  good.

## Deprovisioning: deactivate vs. delete [#deprovisioning-deactivate-vs-delete]

SCIM's standard offboarding action, and orboto's own delete route,
behave differently - know which one your IdP sends before you rely on
either:

* **`PATCH` with `active=false`** (what a SCIM-compliant IdP sends on
  offboarding by default) **deactivates** the orboto user. They can no
  longer sign in, but every ticket, comment, and history item they ever
  touched stays intact and correctly attributed to them - nothing is
  deleted or reassigned.
* **`DELETE` on a user** is a **soft-deactivate by default** - same
  effect as the PATCH case above, and the safe choice for most
  workspaces, since it never destroys history. An operator can flip this
  to a genuine hard row deletion instead (irreversible, removes the row
  outright) via a system-level setting - only do this if your compliance
  posture actually requires purging the row rather than deactivating it.

In practice: unless you've deliberately switched to hard deletion, both
paths are safe and reversible in effect (you can always reactivate a
deactivated user manually in orboto) - what's NOT reversible is losing
track of *when* something changed, which is why every SCIM action is
logged (see Security below).

## Security [#security]

* Tokens are workspace-scoped and stored hashed (SHA-256) - the
  plaintext only ever exists at the moment you mint or rotate it.
* Each token has **per-second and per-day rate budgets**. Exceeding
  either returns HTTP `429` with a `Retry-After` header your IdP's
  provisioning engine should already respect (all four IdPs in the table
  above back off correctly on this).
* Every SCIM operation - create, update, deactivate, delete, and any
  rejected/failed attempt - is recorded in the **sync history** under
  **Admin → SCIM provisioning**, with timestamp, operation, outcome, and
  the error detail on failures. This is the trail an auditor asks for
  when checking identity-management controls (the kind of evidence
  frameworks like SOC 2 or ISO 27001 expect for user lifecycle
  management), and it also feeds the workspace's general audit log and
  compliance export.

{/* screenshot: the SCIM sync history table with a mix of successful and failed operations */}

### Filtering, sorting, and concurrency [#filtering-sorting-and-concurrency]

For IdP engineers or anyone debugging a sync directly against the API:

* The endpoint supports RFC 7644 filtering (`eq`, `ne`, `co`, `sw`,
  `ew`, `gt`, `ge`, `lt`, `le`, `pr`, combined with `and` / `or` / `not`
  and grouping), sorting, and attribute projection (`attributes` /
  `excludedAttributes` to shrink a response to just the fields you
  need).
* Updates use **ETag optimistic concurrency**: a `PUT` or `PATCH` sends
  `If-Match` with the resource's current ETag, and the request is
  rejected if the resource changed since you last read it - this stops
  two concurrent updates from silently clobbering each other, which
  matters if you're scripting bulk changes outside the IdP's normal
  provisioning loop.

## Outbound lifecycle webhook (optional) [#outbound-lifecycle-webhook-optional]

Beyond inbound provisioning, you can set an **outbound webhook URL**
(same **Admin → SCIM provisioning** page) so orboto POSTs every
lifecycle event (`user.created`, `user.updated`, `user.deactivated`,
`user.deleted`) to an endpoint you control - useful for feeding a
downstream audit or SIEM pipeline that wants to know about identity
changes without polling orboto's API. Set a secret alongside the URL and
every delivery carries an `X-Orboto-Signature` HMAC header you can
verify, the same signing scheme orboto's other webhooks use (see the
[API cookbook](/api-cli/cookbook#register-and-consume-a-webhook)
for a worked verification example).

## Interplay with SSO [#interplay-with-sso]

SCIM and [SSO](/admin/identity/sso) solve two different problems
and are meant to run together, not as alternatives:

* **SCIM** manages the **account lifecycle** - who has an orboto
  account at all, and what their profile fields say.
* **SSO** manages **authentication** - how a user proves who they are
  when signing in.

A user provisioned by SCIM has no orboto password; they sign in only
through your IdP via SSO. If you run both, pair them with the
"require 2FA for password accounts" policy scoped to just the accounts
that genuinely remain on local passwords (service accounts, break-glass
admins) - SCIM+SSO users don't need it since they never have a
password to protect.

## Troubleshooting [#troubleshooting]

| Symptom                                                        | Likely cause                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A newly assigned IdP user never appears in orboto              | Check the IdP's provisioning job/log first - most "nothing happened" cases are the IdP-side sync not having run yet (some IdPs provision on a schedule, not instantly) or a failed **Test connection** that was never actually fixed. Then check orboto's sync history for a rejected request with an error detail. |
| Provisioning worked once, then stopped                         | Check whether the token expired, was rotated without updating the IdP, or was accidentally revoked. The sync history will show `401`s once the token stops being valid.                                                                                                                                             |
| Deactivating a user in the IdP doesn't lock them out of orboto | Confirm the IdP is actually configured to send the deprovisioning action on offboarding (some IdPs need this enabled explicitly, it isn't always the default), and check the sync history to see whether the `PATCH active=false` (or `DELETE`) request even arrived.                                               |
| Department / manager fields aren't syncing                     | Those come from the SCIM enterprise-user schema extension - confirm your IdP's provisioning app is actually configured to send that extension's attributes, not just the base user schema.                                                                                                                          |
| Getting `429`s during a bulk provisioning run                  | You're exceeding the token's per-second or per-day rate budget. Most IdPs already throttle and retry on `429` automatically; if yours doesn't, space out the bulk assignment instead of assigning hundreds of users at once.                                                                                        |
| A user was hard-deleted and you need their history back        | If your workspace uses the default soft-deactivate behavior, nothing was actually destroyed - reactivate the user manually in orboto. If hard deletion was explicitly enabled, the row is genuinely gone; restoring it means restoring from a backup (see [Backups](/self-hosting/backups)).                        |


# Symphony (/integrations/symphony)



## What Symphony is [#what-symphony-is]

[Symphony](https://github.com/openai/symphony) is an open specification for
orchestrating fleets of AI coding agents against a ticket tracker: it polls a
tracker for workable issues, dispatches them to coding-agent sessions running
in parallel, tracks each agent's turns and retries, and gates how far an
agent gets before a human (or another check) has to approve. It was
originally written against Linear as the tracker.

orboto ships a **Symphony adapter**: a small set of REST endpoints, shaped
exactly to what Symphony's tracker interface expects, plus a setup wizard
that provisions everything a Symphony fork needs to point at your orboto
workspace instead of Linear. If you're already running (or plan to run) a
Symphony-based agent fleet and want it working your orboto backlog, this is
the integration for that.

If you instead want orboto's own **built-in** agent dispatch - no separate
orchestrator to run - see [Work routing and
fleets](/agents-ai/work-routing) and [Run an agent
fleet](/agents-ai/run-a-fleet) instead. Symphony is for teams who are
already standardized on the Symphony orchestration model and want orboto as
its tracker backend.

## What it connects [#what-it-connects]

A Symphony fork talks to orboto through a handful of endpoints under
`/integrations/symphony/*`, each returning data already shaped as Symphony's
normalized "Issue" - priority mapped to its 1-4 integer scale, labels
lower-cased, blockers joined in, and a ready-to-use git branch name computed
server-side:

| Endpoint                                           | Purpose                                                                                                                                                          |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /integrations/symphony/candidates`            | The tracker's main poll: every issue in the given active-state categories, for one project or several.                                                           |
| `POST /integrations/symphony/by-states`            | Fetch issues by status category across one or more projects.                                                                                                     |
| `POST /integrations/symphony/by-ids`               | Refresh a specific set of issues by ID (Symphony's reconciliation pass).                                                                                         |
| `GET /integrations/symphony/branch-name/:ticketId` | A pure branch-name lookup for workspace-bootstrap hooks that don't need the full issue payload.                                                                  |
| `POST /integrations/symphony/agent-tool/query`     | An optional agent-side tool: lets a running coding-agent turn run an OQL or JQL query against orboto mid-session, without routing back through the orchestrator. |
| `POST /integrations/symphony/agent-events`         | Session lifecycle events (started, turn completed, stalled, ...) an orchestrator can push so orboto's ticket view shows what an agent is doing.                  |

Status is mapped by **category**, not by a project's per-status display
name, since names get renamed ("To Do" → "Backlog") but categories are
stable across every project and instance:

| orboto category | Symphony `active_states` / `terminal_states` |
| --------------- | -------------------------------------------- |
| `todo`          | active                                       |
| `in_progress`   | active                                       |
| `in_review`     | active                                       |
| `done`          | terminal                                     |
| `wont_fix`      | terminal                                     |

### Field mapping [#field-mapping]

| Symphony field              | orboto source                                    | Notes                                                       |
| --------------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
| `id`                        | Ticket ID (UUID)                                 |                                                             |
| `identifier`                | Ticket key                                       | e.g. `ACME-42`.                                             |
| `title`                     | Ticket title                                     |                                                             |
| `description`               | Ticket description                               | Markdown.                                                   |
| `priority`                  | Ticket priority, mapped to an integer            | `blocker=1`, `high=2`, `normal=3`, `low=4`, `trivial=4`.    |
| `state`                     | Status **category**, not name                    | `todo` / `in_progress` / `in_review` / `done` / `wont_fix`. |
| `branch_name`               | Computed from the ticket key + a slugified title | `null` if the project has no connected git repository.      |
| `url`                       | Built from the project key and ticket key        |                                                             |
| `labels`                    | Ticket labels, lower-cased                       |                                                             |
| `blocked_by`                | Open dependency tickets                          | Includes each blocker's id, key, and status category.       |
| `created_at` / `updated_at` | Ticket timestamps                                | ISO-8601.                                                   |

## Setup [#setup]

Setup lives at **Admin → Integrations → Symphony** - a five-step guided
wizard that replaces the manual work of creating a service account,
assigning it to projects, minting an API key, and hand-writing a
`WORKFLOW.md` config block. It's safe to re-run: it reuses an existing
service account and its project memberships rather than creating duplicates.

{/* screenshot: the Symphony Setup Wizard's five steps in Admin → Integrations */}

1. **Service account.** Pick an existing bot/service-account user, or create
   a new one by entering an email and display name (a sensible default is
   something like `symphony-bot@yourcompany.com`, "Symphony"). This is the
   identity every Symphony-dispatched action will be attributed to.
2. **Projects to authorize.** Check every project you want Symphony to see.
   Click **Apply** - the wizard adds the service account to each checked
   project (skipping ones it's already a member of) and shows a per-project
   result.
3. **API key.** Click **Mint API key**. The key is shown exactly once -
   copy it immediately into wherever your Symphony fork's deploy environment
   reads `ORBOTO_TOKEN` from. If you navigate away before copying it, mint a
   new one; the old one still works until you revoke it, but its plaintext
   is gone for good.
4. **WORKFLOW\.md snippet.** The wizard assembles a ready-to-use config block
   from what you picked in steps 1-3 - your instance's own address, the
   `ORBOTO_TOKEN` reference, and the project key(s) you authorized. **Copy**
   or **Download** it as `WORKFLOW.md` and drop it into your Symphony fork's
   repository (wherever your fork's config loader expects it). Replace the
   placeholder prompt body with your team's actual task instructions - what
   "done" means, branch naming, PR conventions - before you rely on it.
5. **Test connection.** Click **Run test** to confirm the service account
   can actually reach each authorized project through the adapter endpoints
   before you wire up a real Symphony deployment against it.

### Choosing a starting configuration [#choosing-a-starting-configuration]

The generated `WORKFLOW.md` is a reasonable default for a small-to-medium
team: moderate concurrency, a 30-second poll interval, generous per-turn
budgets. Depending on how your team wants to run its fleet, you may want to
tune it toward one of two other shapes once you have the wizard's output as
a starting point:

* **Higher concurrency, AI-heavy.** More agents running in parallel, longer
  turn budgets, and the push-triggered re-polling described below turned on
  so dispatch reacts to changes immediately instead of waiting for the next
  poll tick.
* **Conservative, human-in-the-loop.** A single agent at a time, manual
  approval required on file changes and commands, and a longer turn timeout
  to absorb the time a human reviewer takes without tripping Symphony's
  stall detection.

Both are the same `WORKFLOW.md` shape - the settings your Symphony fork's
config schema exposes for concurrency, approval policy, and timeouts - just
tuned differently. Start from what the wizard generates and adjust from
there.

## Usage [#usage]

Once your Symphony fork is deployed with the generated config:

* On its normal poll interval (30 seconds by default), Symphony fetches
  candidate issues from `GET /integrations/symphony/candidates` and
  dispatches agents against whichever ones fit its concurrency limits.
* **Push-triggered re-polling** (optional): subscribe a webhook to the
  `symphony.candidates_changed` event (**Admin → Webhooks → Add**, event
  filter set to just that event) so your fork can flag its candidate list
  dirty and re-poll immediately on a status, assignee, or priority change,
  instead of waiting out the poll interval. This event is also available
  as an [n8n Trigger event](/integrations/n8n-reference#orboto-trigger-events)
  if you'd rather react to it from a workflow than build the listener into
  your fork directly.
* As agents work, each ticket they touch shows an **Agent** tab in its
  ticket detail view (once at least one lifecycle event has been recorded
  for it) with the session's activity - started, each turn, and how it
  ended - so a human glancing at the ticket sees what an agent already did
  without leaving orboto.
* Symphony's own dispatch loop decides claiming, status moves, comments, and
  PR links through the coding agent's normal tool use - the adapter only
  supplies **read** access to issue data plus the small write surface for
  activity events above. It never mutates a ticket's status or content
  directly through these endpoints itself.

## Troubleshooting [#troubleshooting]

| Symptom                                           | Likely cause                                                                                                                                                                                                                                                        |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test connection fails for a project               | The service account isn't actually a member of that project - re-run step 2 of the wizard and confirm it's checked, or check the project wasn't renamed/archived since.                                                                                             |
| Candidates endpoint returns nothing               | Confirm your fork's `active_states` uses orboto's category values (`todo`, `in_progress`, `in_review`) and not a project's display names - a category value like `todo` always matches; a display name like "To Do" only matches if nobody ever renamed the status. |
| Symphony never claims a ticket it should see      | Check the ticket isn't private with the service account excluded from its access list, and that its project is checked in the wizard's authorized-projects step.                                                                                                    |
| Lost the API key before copying it                | Mint a fresh one from the wizard's step 3 - the old key keeps working until you separately revoke it from **Admin → API keys**.                                                                                                                                     |
| `symphony.candidates_changed` webhook never fires | Confirm the webhook is active under **Admin → Webhooks** and its event filter includes that event - it's opt-in, so a webhook that doesn't list it is unaffected by ticket changes.                                                                                 |
| Branch name comes back `null`                     | The ticket's project has no connected git repository - see [Git integration](/integrations#code-repositories-git).                                                                                                                                                  |


# Sending domains and DNS (/mail/domains)



Every email you send has a `from` address, and orboto Mail only sends on
behalf of domains that are verified on your account. Verification is
what lets receiving mail servers (Gmail, Outlook, ...) confirm a message
claiming to be from `you@yourdomain.example` really was authorized by
that domain's owner - without it, transactional email either gets
rejected outright or lands in spam. This page explains what verification
means and walks through adding your own domain; see
[Sending email](/mail/sending#error-responses) for the specific
error a send returns when the `from` domain isn't ready yet.

## If your app runs as an orboto SaaS workspace [#if-your-app-runs-as-an-orboto-saas-workspace]

Nothing to do here. An orboto SaaS workspace connected to orboto Mail
gets a dedicated subdomain (`<your-workspace>.orbo.to`) provisioned and
DKIM-verified automatically the moment you connect - see
[Using orboto Mail from an orboto workspace](/mail/orboto-integration).
SPF and DMARC are configured once at the `orbo.to` root and inherited by
every workspace subdomain, so there's no DNS work on your side at all.
The rest of this page is for a **custom domain** - your own domain name,
used by a standalone application or a self-hosted orboto instance.

## Add a custom domain [#add-a-custom-domain]

```bash
curl https://mail.orboto.io/api/v1/sender-domains \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.example" }'
```

The response includes everything you need to publish:

```json
{
  "id": "b7e6c1a0-...",
  "domain": "yourdomain.example",
  "dkimSelector": "orboto",
  "verificationStatus": "pending",
  "dkimRecords": [
    {
      "name": "orboto._domainkey.yourdomain.example",
      "type": "TXT",
      "value": "v=DKIM1; k=rsa; p=<base64-encoded public key>"
    }
  ],
  "spfRequired": "v=spf1 include:spf.orboto.io ~all",
  "dmarcRecommended": "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@dmarc.orboto.io; ruf=mailto:dmarc-reports@dmarc.orboto.io; aspf=r; adkim=r",
  "mailFromRecords": [
    { "name": "bounces.yourdomain.example", "type": "MX", "value": "feedback-smtp.eu-central-1.amazonses.com", "priority": 10 },
    { "name": "bounces.yourdomain.example", "type": "TXT", "value": "v=spf1 include:amazonses.com ~all" }
  ]
}
```

orboto Mail generates a DKIM keypair for you (this is "BYODKIM" -
Bring-Your-Own-DKIM: orboto Mail owns the key, you publish only the
public half) and keeps the private key encrypted at rest. You never
handle key material yourself.

## The DNS records to publish [#the-dns-records-to-publish]

| Record                  | Type | Name                                   | Value                                                      | Purpose                                                                                                                                                                                                                                                                                |
| ----------------------- | ---- | -------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DKIM                    | TXT  | `orboto._domainkey.yourdomain.example` | from `dkimRecords[0].value` above                          | Cryptographically signs every message so receivers can verify it wasn't altered in transit and really came from you.                                                                                                                                                                   |
| SPF                     | TXT  | `yourdomain.example` (root)            | `v=spf1 include:spf.orboto.io ~all`                        | Authorizes orboto Mail's sending infrastructure to send as your domain. If you already have an SPF record for other mail (e.g. Google Workspace), add `include:spf.orboto.io` to the existing record rather than creating a second TXT record - a domain can only have one SPF record. |
| DMARC                   | TXT  | `_dmarc.yourdomain.example`            | from `dmarcRecommended` above                              | Tells receivers what to do with mail that fails SPF/DKIM, and where to send aggregate reports. Recommended, not required for `verified` status.                                                                                                                                        |
| MAIL FROM (Return-Path) | MX   | `bounces.yourdomain.example`           | `feedback-smtp.eu-central-1.amazonses.com` (priority `10`) | Points bounce handling at a subdomain you own instead of a shared AWS address, which is what makes SPF alignment (and therefore full DMARC pass) possible.                                                                                                                             |
| MAIL FROM (Return-Path) | TXT  | `bounces.yourdomain.example`           | `v=spf1 include:amazonses.com ~all`                        | SPF for the bounce subdomain above.                                                                                                                                                                                                                                                    |

Some DNS providers (notably Route 53 and other strict resolvers) reject
a single TXT value longer than 255 bytes. If a record in the API
response includes a `valueChunks` array alongside `value`, use the
chunks - each is a separate quoted string inside the same TXT record.
Providers like Cloudflare and Google Cloud DNS accept the long single
`value` directly and never need this.

If your domain is on Cloudflare, `POST /v1/sender-domains/:id/cloudflare-auto-setup`
(with a scoped Cloudflare API token in the body) creates every record
above for you automatically instead of pasting them by hand -
`GET /v1/sender-domains/:id/cloudflare-detect` tells you upfront whether
the domain is on Cloudflare at all. Both are also available as buttons
in the dashboard.

{/* screenshot: account.orboto.io/mail/domains - add-domain flow showing the DNS records to publish + Cloudflare auto-setup button */}

## Verifying [#verifying]

DNS changes take time to propagate. Once the records are published,
trigger a check:

```bash
curl https://mail.orboto.io/api/v1/sender-domains/b7e6c1a0-.../verify \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here"
```

`verificationStatus` moves through these states:

| Status              | Meaning                                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `pending`           | Records not detected yet. Re-check after DNS propagation (a few minutes to a few hours, depending on your provider and TTLs).        |
| `verified`          | DKIM confirmed. Sending from this domain now works.                                                                                  |
| `temporary-failure` | A transient error on the verification side. Re-check again shortly - no action needed on your part.                                  |
| `failed`            | Records were published, then removed or changed after the domain had verified. Sending is blocked until you republish and re-verify. |

Only `verified` domains can be used as the `from` address on a send -
see the `from_domain_not_verified` error on the
[sending page](/mail/sending#error-responses).

## Removing a domain [#removing-a-domain]

```bash
curl https://mail.orboto.io/api/v1/sender-domains/b7e6c1a0-... \
  -X DELETE \
  -H "Authorization: Bearer oms_live_your_key_here"
```

This deregisters the sending identity on orboto Mail's side. It does not
remove the DNS records from your provider - do that separately if you no
longer want them published.

## Troubleshooting [#troubleshooting]

| Symptom                                                                | Fix                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Still `pending` after 24 hours                                         | Double-check the DKIM TXT record's name and value were copied exactly - a trailing dot, wrong selector, or truncated `value` (see the `valueChunks` note above) is the usual cause. Some registrars also silently drop long TXT values without an error - try `valueChunks` even if you initially used `value`. |
| `verified`, then dropped to `failed`                                   | Something changed the DNS record after it verified - a provider migration, a DNS zone reset, or an accidental edit. Republish the exact record from a fresh `GET /v1/sender-domains/:id` call (don't reuse an old copy) and verify again.                                                                       |
| `409 reserved_domain`                                                  | The domain (or a subdomain of it) is reserved for orboto's own infrastructure and can't be claimed by a customer account.                                                                                                                                                                                       |
| `409 domain_already_added`                                             | The domain is already on your account - the error includes the existing domain's id; call `/verify` on that id instead of creating a new one.                                                                                                                                                                   |
| I have an existing SPF record for other email (Google Workspace, etc.) | Don't add a second SPF TXT record - a domain can only have one. Merge `include:spf.orboto.io` into your existing SPF record's `include:` list instead.                                                                                                                                                          |
| DMARC reports still show failures after `verified`                     | Confirm the MAIL FROM records were also published - DKIM alone gives DMARC pass, but full SPF alignment (used as failover if the primary region's DKIM check has a transient issue) needs the `bounces.yourdomain.example` MX + TXT pair too.                                                                   |


# orboto Mail (/mail)



Transactional email is the mail your application sends because something
happened - a signup confirmation, a password reset, an invoice, a
workflow notification. It is different from marketing email (newsletters,
campaigns) in one important way: each message is triggered by one user's
action and that user expects to receive it. Getting it delivered reliably
requires infrastructure most teams would rather not build themselves:
a sending service with a good reputation, DKIM/SPF/DMARC configured
correctly, bounce and complaint handling, and a record of what was sent.

**orboto Mail** (internally "OMS") is that infrastructure, run for you.
It is a standalone product - any application can send through it, with or
without an orboto workspace - built on Amazon SES with EU-only data
residency (Frankfurt + Dublin), and it plugs directly into an orboto
workspace's outbound email (invites, notifications, password resets) with
a single click. See [Using orboto Mail from an orboto workspace](/mail/orboto-integration)
for that specific path; the rest of this section documents orboto Mail as
a product on its own.

## What you get [#what-you-get]

* **A single send API.** `POST /v1/send` takes a from-address, a
  recipient, and either raw HTML/text or a server-side template, and
  hands the message to SES across two EU regions with automatic
  failover. See [Sending email](/mail/sending).
* **Batch sending.** `POST /v1/send/batch` sends up to 100 messages in
  one call instead of looping client-side.
* **Server-side templates.** Store a subject + HTML/text body with a
  JSON-schema-validated set of variables, then send by referencing the
  template's id instead of re-sending the markup every time. See
  [Templates](/mail/templates).
* **Verified sending domains.** Add your own domain, publish the DNS
  records orboto Mail gives you, and send as `you@yourdomain.example`
  with DKIM, SPF, and DMARC all correctly aligned. See
  [Sending domains and DNS](/mail/domains).
* **Suppression list + delivery events.** Hard bounces and spam
  complaints are automatically added to a per-account suppression list
  and excluded from future sends; every bounce, complaint, delivery, and
  quota event can be pushed to your own webhook endpoint. See
  [Suppression and delivery events](/mail/suppression-and-events).
* **A monthly quota with clear failure modes.** Every account has a
  monthly sending quota; `GET /v1/quota` reports current usage, and a
  send that would exceed the quota fails with a specific, actionable
  reason instead of a generic error.
* **Attachments, CC/BCC, and tags.** Up to 20 attachments and 30 MB
  per message, up to 50 CC and 50 BCC recipients, and a free-form tag
  bag on every send for your own reporting.
* **Optional open tracking.** Per sending domain, you can opt in to a
  tracking pixel that records opens - off by default, since it touches
  recipient privacy.

## Two ways to use it [#two-ways-to-use-it]

| Path                          | Who it's for                                                                                                     | Where                                                                 |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Direct API / SDK**          | Any application, orboto workspace or not                                                                         | `mail.orboto.io` - REST API, described in this section                |
| **orboto workspace provider** | An orboto workspace that wants its own outbound email (invites, notifications, resets) to go through orboto Mail | Admin → System Settings → Email delivery, inside your orboto instance |

Both paths hit the same API and the same account - the workspace
integration is a connect-once shortcut, not a different product.

## Account and dashboard [#account-and-dashboard]

There is no dashboard on `mail.orboto.io` itself - that host is the API
endpoint plus this documentation. Your account, billing, API keys,
sending domains, templates, suppression list, and webhook subscriptions
are all managed at **account.orboto.io/mail** once you've signed up.

{/* screenshot: account.orboto.io/mail overview dashboard - usage this month, quick links to domains/templates/suppression */}

orboto Mail is a **cloud-only** service - there is no self-hosted
deployment. If you self-host orboto itself, you still reach orboto Mail
over the public API exactly like any other application.

## Troubleshooting [#troubleshooting]

| Symptom                                                                                   | Likely cause                                                                                                                                                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| I don't know where to sign up or see usage                                                | There's no dashboard on `mail.orboto.io`. Go to `account.orboto.io/mail` for account, billing, domains, and API keys.                                               |
| My app already sends email through my orboto workspace - do I need to sign up separately? | No. Connecting a workspace to orboto Mail (see [orboto integration](/mail/orboto-integration)) provisions an account and a sending subdomain for you automatically. |
| I want to send marketing/newsletter email through this                                    | orboto Mail is transactional-only (triggered by a single user action). It is not built or priced for bulk marketing sends.                                          |


# Using orboto Mail from an orboto workspace (/mail/orboto-integration)



An orboto workspace sends its own transactional email: invitations,
in-app notification emails, password resets, digest summaries. That
outbound mail needs a provider configured somewhere, and **orboto Mail
Service** is the recommended one - it's EU-hosted, requires no separate
signup, and (for a cloud SaaS workspace) provisions a verified sending
subdomain automatically. This page covers connecting an orboto workspace
to it; for the standalone product API itself, start at
[orboto Mail](/mail).

## Connecting [#connecting]

Go to **Admin → System Settings → Email delivery** and set **Provider*&#x2A;
to &#x2A;*"orboto Mail Service - recommended"**. A connection card appears
below the field group with two ways to finish setup:

{/* screenshot: Admin -> System Settings -> Email delivery, Provider dropdown set to "orboto Mail Service", connection card showing the "Connect to orboto Mail" button */}

### One-click connect (recommended) [#one-click-connect-recommended]

Click **Connect to orboto Mail**. You're redirected to
`account.orboto.io/mail` to approve the connection; when you come back,
your workspace has:

* an orboto Mail account (created automatically if you didn't already
  have one),
* an API key issued and stored for you - you never see or handle the
  raw key,
* a verified sending domain (`<your-workspace>.orbo.to`) with DKIM
  already configured, so mail starts flowing with zero DNS work,
* sending capacity billed as part of your existing orboto subscription
  rather than a separate account to manage.

The card then shows **Connected**, the resolved from-address, and the
OMS endpoint in use. A **Disconnect** button revokes the connection on
both sides and clears the local configuration - outbound email stops
working until you configure a provider again.

### Manual API key [#manual-api-key]

If you'd rather not use the OAuth flow - common for self-hosted
instances, or when an operator issues keys centrally - fill in the
fields directly instead of clicking Connect:

| Field                                   | Value                                                                                                                                                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OMS API key**                         | An `oms_live_...` key from [account.orboto.io/mail/api-keys](https://account.orboto.io) (see [Sending email](/mail/sending#base-url-and-authentication) for how keys work), or one issued by your operator. |
| **From address**                        | A verified sender on that account, e.g. `orboto <noreply@yourdomain.example>` - see [Sending domains and DNS](/mail/domains) to verify one.                                                                 |
| **OMS base URL*&#x2A; &#x2A;(optional)* | Defaults to `https://mail.orboto.io`. Only change this for a self-hosted or staging orboto Mail deployment.                                                                                                 |

A connection made this way shows as "Manually pasted API key (no
connection-id)" on the card - disconnecting only clears the local
configuration, it doesn't notify or revoke anything on the orboto Mail
side (there's nothing to revoke: you control the key directly, so revoke
it yourself at `account.orboto.io/mail/api-keys` if needed).

## Verifying it works [#verifying-it-works]

Use the **Send test email** field at the bottom of the Email delivery
section: enter an address and send. A successful test confirms the
whole path - provider selection, credentials, and sender-domain
verification - in one click, without needing to trigger a real
invitation or notification.

{/* screenshot: Email delivery section, "Send test email" row with an address field and result message */}

## How your workspace picks a provider [#how-your-workspace-picks-a-provider]

Email delivery isn't limited to orboto Mail - System Settings also
supports Resend and a plain SMTP server, and picks between them in this
order: an explicit **Provider** selection always wins; if it's unset,
your workspace prefers orboto Mail if an API key is present, then
Resend, then SMTP. If you're running on orboto's managed cloud, your
workspace may already have orboto Mail configured for you by the
operator as part of provisioning - the Email delivery section still
shows and lets you override it.

## Troubleshooting [#troubleshooting]

| Symptom                                                  | Fix                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect to orboto Mail** button does nothing or errors | Check your workspace can reach `account.orboto.io` (outbound HTTPS), and check the system logs for the connect attempt. You can always fall back to pasting an API key manually while investigating.                                                                                                                                                                 |
| Test email fails with a from-domain error                | Your **From address** field's domain isn't verified yet on the connected orboto Mail account. If you connected via OAuth, the `<workspace>.orbo.to` domain should already be verified - check the from-address actually uses that domain. If you pasted a manual key against your own custom domain, verify it first - see [Sending domains and DNS](/mail/domains). |
| Test email fails with an authentication error            | The API key is invalid or was revoked - most commonly because the connection was disconnected from the `account.orboto.io/mail` side. Reconnect, or paste a fresh key.                                                                                                                                                                                               |
| I disconnected by mistake and workspace email stopped    | Outbound email has no automatic fallback provider - reconnect (or select a different provider) in Email delivery. Nothing queued during the outage is lost; it simply wasn't sent, so time-sensitive mail like password resets should be re-triggered by the affected user.                                                                                          |
| I want to see exactly what was sent                      | `account.orboto.io/mail/sends` shows your connected account's full send history, or query `GET /v1/sends` directly - see [Sending email](/mail/sending#viewing-what-was-sent).                                                                                                                                                                                       |


# Sending email (/mail/sending)



This page covers the direct REST API. Everything here works the same
whether or not your application is an orboto workspace.

## Base URL and authentication [#base-url-and-authentication]

```
https://mail.orboto.io/api/v1/*
```

Every request carries a Bearer token:

```
Authorization: Bearer oms_live_<your-key>
```

Keys look like `oms_live_...` for production sending or `oms_test_...`
for a sandbox key, and are managed at **account.orboto.io/mail/api-keys**
(create, name, rotate, revoke). {/* screenshot: account.orboto.io/mail/api-keys - list + create dialog showing the plaintext key shown once */}
The full secret is shown exactly once, at creation - orboto Mail only
ever stores a salted hash of it, so a lost key can't be recovered, only
rotated. If your orboto workspace is connected to orboto Mail (see
[orboto integration](/mail/orboto-integration)), a key is issued for
you automatically and you don't need to visit the dashboard for this
step.

## Send a single email [#send-a-single-email]

```bash
curl https://mail.orboto.io/api/v1/send \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Support <support@yourdomain.example>",
    "to": "user@example.com",
    "subject": "Welcome to Acme",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "text": "Welcome! Thanks for signing up.",
    "tags": { "workflow": "welcome" }
  }'
```

A successful send returns `200`:

```json
{
  "messageId": "0100019a-1b2c-4d5e-8f90-abcdef123456",
  "status": "queued",
  "overage": false,
  "remainingQuota": {
    "current": 48,
    "total": 10000,
    "resetAt": "2026-09-01T00:00:00.000Z",
    "percentUsed": 0.0048,
    "softWarnAt": 0.8,
    "softWarnTriggered": false,
    "dailyCap": null,
    "creditBalance": 0
  }
}
```

`status` is always `"queued"` on success - orboto Mail hands the message
to SES synchronously and returns immediately; delivery, bounce, and
complaint outcomes arrive later as [delivery events](/mail/suppression-and-events).
`remainingQuota` reports the account's quota state after this send so
you can decide client-side whether to slow down before the next one.

### Request fields [#request-fields]

| Field                      | Required      | Notes                                                                                                                                                                  |
| -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`                     | yes           | Must be on a [verified sending domain](/mail/domains) for your account. Accepts a bare address or `Display Name <address>`.                                            |
| `to`                       | yes           | A single recipient address.                                                                                                                                            |
| `cc`, `bcc`                | no            | Arrays, up to 50 addresses each. Bcc recipients never appear in headers seen by anyone else on the message.                                                            |
| `subject`                  | conditionally | Required unless `templateId` supplies one. Max 998 characters (RFC 5322 line length).                                                                                  |
| `html`, `text`             | conditionally | At least one of `html`, `text`, or `templateId` is required. `html` and `text` cannot be combined with `templateId` in the same call - pick raw content or a template. |
| `templateId` + `variables` | no            | Send via a [stored template](/mail/templates) instead of raw content.                                                                                                  |
| `tags`                     | no            | A flat object of string keys/values (max 256 chars each), stored on the send record for your own filtering/reporting.                                                  |
| `attachments`              | no            | Array, max 20 items. See below.                                                                                                                                        |

### Attachments [#attachments]

```json
{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "<base64-encoded file bytes>"
    }
  ]
}
```

Up to 20 attachments per send, base64-encoded in the JSON body, with a
combined decoded size limit of 30 MB. Each entry also accepts an
optional `contentId` for inline references (e.g. an image referenced
from the HTML body via `cid:`).

## Send a batch [#send-a-batch]

```bash
curl https://mail.orboto.io/api/v1/send/batch \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "from": "support@yourdomain.example", "to": "a@example.com", "subject": "Hi A", "html": "<p>Hi A</p>" },
      { "from": "support@yourdomain.example", "to": "b@example.com", "subject": "Hi B", "html": "<p>Hi B</p>" }
    ]
  }'
```

`POST /v1/send/batch` runs every message through the same validation,
quota, and send pipeline as a single send, up to 100 messages per call.
It always returns `200`, even if every message failed - read `summary`
and each item's `ok` flag rather than the HTTP status:

```json
{
  "results": [
    { "index": 0, "ok": true, "messageId": "...", "status": "queued", "overage": false },
    { "index": 1, "ok": false, "error": "recipient_suppressed", "message": "..." }
  ],
  "remainingQuota": { "...": "last snapshot after the batch" },
  "summary": { "queued": 1, "rejected": 0, "suppressed": 1, "skipped": 0 }
}
```

Messages are processed in array order. If the account's quota runs out
partway through the batch, every remaining item comes back with
`quotaSkipped: true` instead of being retried - the quota won't refill
mid-batch, so there's no point checking again.

## Checking your quota without sending [#checking-your-quota-without-sending]

```bash
curl https://mail.orboto.io/api/v1/quota \
  -H "Authorization: Bearer oms_live_your_key_here"
```

Returns the same `remainingQuota` shape shown above, wrapped in
`{ "quota": { ... } }` - useful before kicking off a large batch, or for
your own usage dashboards.

## Viewing what was sent [#viewing-what-was-sent]

```bash
curl "https://mail.orboto.io/api/v1/sends?limit=20&status=bounced" \
  -H "Authorization: Bearer oms_live_your_key_here"
```

`GET /v1/sends` lists your account's sends, most-recent first, cursor-
paginated via `?cursor=<value>&limit=<1-100>` (`nextCursor` in the
response feeds the next call). Filter with `status`
(`queued`/`delivered`/`bounced`/`complained`/`rejected`), `region`
(`eu-central-1`/`eu-west-1`), or `since` (ISO timestamp). `GET
/v1/sends/:id` returns one send's full detail, including open-tracking
counters if enabled on the sending domain. The same history is browsable
at **account.orboto.io/mail/sends**.

{/* screenshot: account.orboto.io/mail/sends - filterable send history table with status chips */}

## Error responses [#error-responses]

Every rejection returns a JSON body with `error`, `reason`, and a
human-readable `message`. The reason values you'll actually hit:

| HTTP | `reason`                                 | Meaning                                                                                                                                                                           |
| ---- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `from_domain_not_authorized`             | The `from` address's domain isn't on this account at all. Add it - see [Sending domains](/mail/domains).                                                                          |
| 400  | `from_domain_not_verified`               | The domain is on the account but its DNS records aren't verified yet.                                                                                                             |
| 400  | `subject_required`                       | No `subject` given and no `templateId` to supply one.                                                                                                                             |
| 400  | `template_variable_validation`           | `variables` didn't satisfy the template's schema.                                                                                                                                 |
| 422  | `recipient_suppressed`                   | The recipient is on your [suppression list](/mail/suppression-and-events) (a previous hard bounce, complaint, or manual add). The send is skipped and does **not** consume quota. |
| 402  | `quota_exhausted_*` / `payment_required` | Monthly quota (and any overage allowance) is used up. `message` explains the specific reason and what to do next.                                                                 |
| 503  | `send_failed` / `wallet_unavailable`     | A transient upstream problem (both SES regions unreachable, or - for above-quota sends - the billing wallet couldn't be reached). Safe to retry.                                  |

## Troubleshooting [#troubleshooting]

| Symptom                                                        | Fix                                                                                                                                                                       |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 token_missing` / `token_malformed`                        | Check the `Authorization: Bearer oms_live_...` header is present and the key wasn't truncated when copied.                                                                |
| `401 token_revoked`                                            | The key was revoked (manually, or because the OAuth connection it came from was disconnected). Issue a new one.                                                           |
| `400 from_domain_not_authorized`                               | The `from` address's domain has to be added and verified first - see [Sending domains and DNS](/mail/domains).                                                            |
| `422 recipient_suppressed` on an address you expect to be fine | Check `GET /v1/suppression/:email` - a past bounce or complaint may have added it. Remove it via `DELETE /v1/suppression/:email` if it was a false positive.              |
| Send succeeds (`200 queued`) but the recipient never got it    | Query `GET /v1/sends/:id` a little later for the delivered/bounced outcome, or subscribe a [webhook](/mail/suppression-and-events) to get notified the moment it changes. |
| Getting `404`/`405` on every call                              | Almost always a missing or duplicated `/api` segment - the correct base is `https://mail.orboto.io/api/v1/...`.                                                           |


# Suppression and delivery events (/mail/suppression-and-events)



## The suppression list [#the-suppression-list]

When a recipient's mail server permanently rejects a message ("this
mailbox doesn't exist") or the recipient marks it as spam, orboto Mail
automatically adds that address to your account's **suppression list**
and stops sending to it. This protects your sending reputation - mail
providers penalize senders who keep hitting invalid addresses or
generating complaints, and one bad list can hurt deliverability for
every other recipient too.

Every send checks the suppression list first. A suppressed recipient
gets skipped with a `422 recipient_suppressed` response (see
[Sending email](/mail/sending#error-responses)) and, importantly,
**does not consume your quota** - you're never charged for a send that
was blocked.

| Source        | When it's added                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `hard-bounce` | The receiving server permanently rejected the message (invalid address, domain doesn't exist, mailbox disabled). |
| `complaint`   | The recipient marked the message as spam/junk.                                                                   |
| `manual`      | You added it yourself - via the API or the dashboard - typically for an explicit unsubscribe request.            |

### Managing entries [#managing-entries]

```bash
# Check one address
curl https://mail.orboto.io/api/v1/suppression/user@example.com \
  -H "Authorization: Bearer oms_live_your_key_here"

# Add one manually (e.g. an explicit opt-out request)
curl https://mail.orboto.io/api/v1/suppression \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "reason": "manual" }'

# Remove a false positive
curl https://mail.orboto.io/api/v1/suppression/user@example.com \
  -X DELETE \
  -H "Authorization: Bearer oms_live_your_key_here"

# List, paginated, optionally filtered by reason
curl "https://mail.orboto.io/api/v1/suppression?limit=20&reason=hard-bounce" \
  -H "Authorization: Bearer oms_live_your_key_here"
```

Adding an address that's already suppressed is a no-op (not an error) -
safe to call repeatedly. Removing an address that was auto-added by a
hard bounce is appropriate only when you're confident the underlying
problem is fixed (a typo the recipient corrected, a mailbox that was
temporarily over quota and is now active again); otherwise the next send
will very likely bounce again and re-add it.

{/* screenshot: account.orboto.io/mail/suppression - filterable list with reason badges and a remove action */}

## Delivery events (webhooks) [#delivery-events-webhooks]

Suppression handles the send-time consequence of a bad address
automatically. If you want to *react* to what happens to a message after
it's sent - update a user's profile when their email bounces, alert your
team when quota is running low - subscribe a webhook.

```bash
curl https://mail.orboto.io/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example.com/webhooks/orboto-mail",
    "label": "production",
    "eventFilters": ["bounce.permanent", "complaint", "delivery"]
  }'
```

The response includes `secret` - a signing secret shown **exactly once**.
Omit `eventFilters` (or pass an empty array) to receive every event
type instead of a subset.

### Event types [#event-types]

| Event                                       | Fires when                                                                                                                                                |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delivery`                                  | The recipient's mail server accepted the message.                                                                                                         |
| `bounce.permanent`                          | A hard bounce - the address is also added to your suppression list.                                                                                       |
| `bounce.transient`                          | A soft bounce (mailbox full, server temporarily unavailable) - not added to suppression; the address may succeed on a later send.                         |
| `complaint`                                 | The recipient marked the message as spam - also added to your suppression list.                                                                           |
| `email.opened`                              | The recipient's mail client loaded the tracking pixel, if [open tracking](/mail/domains) is enabled on the sending domain. Fires once, on the first open. |
| `quota.soft-warn-80` / `quota.soft-warn-95` | Monthly usage crossed 80% / 95% of your base quota.                                                                                                       |
| `quota.exhausted-base`                      | Base monthly quota is used up.                                                                                                                            |
| `quota.exhausted-cap`                       | Above-quota (overage) usage hit its account cap too.                                                                                                      |

Each delivery is POSTed as JSON:

```json
{
  "event": "bounce.permanent",
  "timestamp": "2026-08-30T12:00:00.000Z",
  "data": { "messageId": "...", "to": "user@example.com", "bounceType": "Permanent", "suppressionAdded": true }
}
```

with three headers on every request:

```
X-OMS-Webhook-Id: <your webhook subscription id>
X-OMS-Event: bounce.permanent
X-OMS-Signature: t=1735000000, v1=<hex hmac-sha256>
```

### Verifying the signature [#verifying-the-signature]

`v1` is `HMAC_SHA256(your_signing_secret, "<t>.<raw request body>")`,
hex-encoded. Recompute it on your side and compare:

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function isValidOmsWebhook(secret, signatureHeader, rawBody, toleranceSeconds = 300) {
  const tMatch = /t=(\d+)/.exec(signatureHeader);
  const vMatch = /v1=([0-9a-f]+)/.exec(signatureHeader);
  if (!tMatch || !vMatch) return false;

  const t = Number(tMatch[1]);
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const got = vMatch[1];
  return got.length === expected.length &&
    timingSafeEqual(Buffer.from(got, 'hex'), Buffer.from(expected, 'hex'));
}
```

Use the **raw** request body (before any JSON parsing) when computing
the HMAC - re-serializing a parsed object can produce different bytes
(key order, whitespace) and break the signature check. The `t=` value
also doubles as replay protection: reject anything older than a few
minutes, as the example above does.

### Managing subscriptions [#managing-subscriptions]

| Method + path                         | Purpose                                                                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/webhooks`                    | List your subscriptions (signing secret never included).                                                                          |
| `GET /v1/webhooks/:id`                | Get one.                                                                                                                          |
| `PATCH /v1/webhooks/:id`              | Update `url`, `label`, `eventFilters`, or `enabled` (set `enabled: false` to pause deliveries without deleting the subscription). |
| `DELETE /v1/webhooks/:id`             | Remove it.                                                                                                                        |
| `POST /v1/webhooks/:id/rotate-secret` | Issue a new signing secret - the old one stops working immediately. Returns the new plaintext secret once.                        |

`url` must be `https://` (plain `http://` is only accepted for
`localhost`/`127.0.0.1`, for local development). orboto Mail retries a
failing delivery with backoff; `GET /v1/webhooks/:id` reports
`lastSuccessAt`, `lastFailureAt`, and `lastFailureReason` so you can see
whether deliveries are actually landing.

## Troubleshooting [#troubleshooting]

| Symptom                                                                    | Fix                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A known-good address keeps getting `recipient_suppressed`                  | It was likely added by an earlier bounce or complaint. Check `GET /v1/suppression/:email` for the `reason` and `addedAt`, then `DELETE` it if the underlying issue is genuinely fixed.                                                                                                      |
| My webhook isn't receiving anything                                        | Confirm `enabled` is `true` and the event actually happened - `eventFilters` defaults to nothing sent unless you either list the event explicitly or leave the array empty to receive everything. Check `lastFailureReason` on `GET /v1/webhooks/:id` for delivery errors on your endpoint. |
| Signature verification always fails                                        | Almost always caused by re-serializing the JSON body before hashing it - hash the exact raw bytes you received, not a re-`JSON.stringify`'d copy.                                                                                                                                           |
| I rotated my secret and now nothing verifies                               | Expected - a rotation immediately invalidates the previous secret for every future delivery. Update your verification code with the new `secret` returned from the rotate call.                                                                                                             |
| I want to stop bounces from generating a webhook call but keep suppression | Not separable per-event today - suppression and its webhook fire together. `PATCH` your subscription's `eventFilters` to drop `bounce.permanent`/`complaint` if you only want the suppression side-effect without the notification.                                                         |


# Templates (/mail/templates)



A **template** is a subject and body stored on your orboto Mail account
instead of inside your application code. This matters for two reasons:
you can update the wording of a transactional email (a welcome message, a
password reset) without a deploy, and a template can validate its own
variables so a caller that forgets one gets a clear error instead of a
half-rendered email reaching a customer.

## Create a template [#create-a-template]

```bash
curl https://mail.orboto.io/api/v1/templates \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome",
    "subject": "Welcome to Acme, {{name}}!",
    "bodyHtml": "<h1>Hi {{name}}</h1><p>Activate your account: <a href=\"{{activationUrl}}\">click here</a>.</p>",
    "bodyText": "Hi {{name}}, activate your account: {{activationUrl}}",
    "variablesSchema": {
      "type": "object",
      "required": ["name", "activationUrl"],
      "properties": {
        "name": { "type": "string" },
        "activationUrl": { "type": "string", "format": "uri" }
      }
    }
  }'
```

Placeholders use `{{variableName}}` syntax in both `subject` and the
body fields. An unknown placeholder (a typo, or a variable you forgot to
pass) renders as an empty string rather than failing the send - so a
mistake shows up as missing text in the delivered email, not a crash.
Values substituted into `bodyHtml` are HTML-escaped automatically, so a
variable containing `<script>` or similar can't inject markup into the
rendered page.

`variablesSchema` is optional but recommended. It's a small subset of
JSON Schema: `required` (array of variable names that must be present),
and per-variable `type` (`string`/`number`/`integer`/`boolean`), an
optional `format` (`uri` or `email`, checked with a light regex, string
variables only), and an optional `enum` of allowed values. A template
created without a schema accepts any variables you send it.

The response echoes the stored template with its `id`, plus
`createdAt`/`updatedAt`. Every create and update also appends a version
snapshot server-side, so you (or the [account.orboto.io/mail/templates](https://account.orboto.io)
dashboard) can see the template's edit history.

{/* screenshot: account.orboto.io/mail/templates - editor with live preview and version history sidebar */}

## Send with a template [#send-with-a-template]

```bash
curl https://mail.orboto.io/api/v1/send \
  -X POST \
  -H "Authorization: Bearer oms_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Support <support@yourdomain.example>",
    "to": "user@example.com",
    "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "variables": { "name": "Alice", "activationUrl": "https://app.example.com/activate/abc123" }
  }'
```

Pass `templateId` and `variables` to `POST /v1/send` (or as one entry in
a [batch send](/mail/sending#send-a-batch)) instead of `html`/`text`

* the two are mutually exclusive in the same call. `subject` is optional
  when a template is used: if you omit it, the template's own subject
  (with its own `{{}}` placeholders resolved from `variables`) is used.
  If `variables` fails the template's schema, the send returns `400
  template_variable_validation` with one message per failed check, and
  nothing is sent.

## Managing templates [#managing-templates]

| Method + path              | Purpose                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `GET /v1/templates`        | List every template on the account, most recently updated first.                   |
| `GET /v1/templates/:id`    | Fetch one template, including its `variablesSchema`.                               |
| `POST /v1/templates`       | Create (shown above).                                                              |
| `PATCH /v1/templates/:id`  | Update any subset of `name`, `subject`, `bodyHtml`, `bodyText`, `variablesSchema`. |
| `DELETE /v1/templates/:id` | Remove a template. Existing `oms_sends` history rows that used it are unaffected.  |

Templates are private to your account - there is no shared or
cross-account template library.

## Troubleshooting [#troubleshooting]

| Symptom                                                               | Fix                                                                                                                                                                                           |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 template_variable_validation`                                    | Read the `message` field - it lists every failing variable by name and what's wrong (missing, wrong type, bad format, not in the enum). Fix the caller's `variables` payload.                 |
| A placeholder like `{{usrname}}` shows up literally, or renders blank | An unknown placeholder renders as empty, it doesn't error. Check the variable name matches exactly (case-sensitive) between the template body and your `variables` object.                    |
| `404 template_not_found` when sending                                 | The `templateId` doesn't exist on this account, or belongs to a different account/key. Confirm with `GET /v1/templates`.                                                                      |
| I need conditionals / loops in a template                             | The renderer only does flat `{{variableName}}` substitution - no logic. Build any conditional content into the `variables` payload before sending (e.g. pre-render an HTML fragment) instead. |


# Bring your own provider (/orboto-ai/byo-keys)



Instead of [orboto AI](/orboto-ai), you can connect an account you
already have with another AI provider. orboto then calls that provider
directly with your key, and your usage is billed by that provider under
your own account with them - orboto's [usage and
limits](/orboto-ai/usage-and-limits) mechanics don't apply to it.

This is a plain settings choice, not a one-way migration: you can switch
back to orboto AI at any time, and - for the reason explained below -
switching your embeddings provider away from orboto AI on a managed
workspace is remembered even across restarts, so it's never silently
switched back for you.

## Supported providers [#supported-providers]

**Admin -> AI settings**' "Own provider" option supports:

* **OpenAI**
* **Anthropic (Claude)** - no embeddings endpoint; pair it with orboto AI,
  OpenAI, or another embeddings-capable provider for search and Ask-Docs.
* **Google Gemini**
* **GitHub Copilot** - Business or Enterprise seat only. An individual
  Copilot subscription's terms of service don't permit this kind of use.
* **Ollama** - self-hosted, native API, no key required.
* **Any OpenAI-compatible endpoint** - OpenRouter, Groq, DeepSeek, LM
  Studio, vLLM, and others that speak the OpenAI API shape. A preset
  picker autofills the base URL and a sensible default model for known
  vendors.

Full setup steps (loading a provider's model catalog, presets, per-feature
model overrides) are in [AI providers and
models](/admin/ai/ai#picking-a-provider).

## Chat and embeddings are independent [#chat-and-embeddings-are-independent]

Choosing "own provider" for chat and completion doesn't change your
embeddings provider, and vice versa - they're two separate settings.
That's intentional: Anthropic and Copilot don't have an embeddings
endpoint at all, so a workspace using either for chat needs a different
provider (orboto AI, OpenAI, Gemini, Ollama, or an OpenAI-compatible
endpoint) for embeddings regardless of what powers chat.

## Switching is lossless [#switching-is-lossless]

Whichever provider you switch away from - orboto AI or another one - has
its base URL, key and model stashed on the server. Switching back later
restores exactly what you had, rather than making you re-enter it from
scratch. This applies to both the chat and embeddings choices, in either
direction.

## The managed-workspace opt-out [#the-managed-workspace-opt-out]

On a managed cloud workspace, orboto AI's embeddings are active by
default. If you explicitly switch the **embeddings** provider to
something else, that choice is durable: it's recorded as "bring your own"
for embeddings specifically, and survives restarts and platform-side key
rotations - orboto never re-activates managed embeddings under you without
an explicit action on your part.

This opt-out is scoped to embeddings only. Switching the **chat**
provider away from orboto AI doesn't need an equivalent flag, because
chat has no automatic wiring to protect against in the first place - it's
just whatever provider is currently configured.

To switch embeddings back to orboto AI on a managed workspace, either:

* click &#x2A;*Use orboto AI (managed)** in the Embeddings subsection of
  **Admin -> AI settings**, or
* pick **orboto AI** again from the embeddings provider dropdown.

Either one clears the opt-out and restores managed embeddings.

## Troubleshooting [#troubleshooting]

* **The embeddings provider dropdown doesn't offer Anthropic or GitHub
  Copilot.** Expected - neither has an embeddings endpoint, so they're
  intentionally absent from that list even though both appear for chat.
* **I switched away from orboto AI and now key rotations on the platform
  side don't affect my workspace.** Expected for embeddings, as described
  above - that's what the durable opt-out is for. It has no effect on
  your own provider's key, which you manage entirely yourself.
* **"Load models" fails after pasting a key.** Usually a wrong base URL or
  an invalid/expired key - the error shows inline, and you can type a
  model id by hand while you fix the wiring.
* **I want orboto AI for one capability and my own provider for the
  other.** Fully supported - set them independently in **Admin -> AI
  settings**; see [Chat and embeddings are
  independent](#chat-and-embeddings-are-independent) above.


# orboto AI (/orboto-ai)



Every AI feature in orboto - the [AI Chat assistant](/user-guide/ai-assistant),
semantic search, duplicate and related-ticket detection, ticket and doc
summaries, Ask-Docs, translation, and more - runs on a model provider
configured once in **Admin -> AI settings**. **orboto AI** is one option
for that provider: a model connection orboto operates on your behalf, so
these features work without you first creating an account with an AI
company, generating an API key there, and pasting it in.

This page explains what orboto AI is and where it's available. For the
metered side (what's included, what happens when you use more than that),
see [Usage and limits](/orboto-ai/usage-and-limits). If you'd rather
connect your own provider account instead - or in addition, since chat and
embeddings are configured independently - see
[Bring your own provider](/orboto-ai/byo-keys).

## What it covers [#what-it-covers]

Every AI feature draws on one of two independent capabilities, and orboto
AI supplies both:

* **Chat and completion** - the model behind the AI Chat assistant, ticket
  and doc summaries, translation, and every other feature that generates
  text.
* **Embeddings** - the vector model behind semantic search, duplicate and
  related-ticket detection, and Ask-Docs.

Because the two are configured independently, you can also mix: for
example, use your own Anthropic account for chat (Anthropic has no
embeddings endpoint) while keeping orboto AI for embeddings, or the
reverse. See [Bring your own provider](/orboto-ai/byo-keys) for how
that independence works in the settings UI.

orboto AI is hosted in the EU.

## Where it's available [#where-its-available]

{/* screenshot: AI settings page, the "orboto AI" card active with the managed key note */}

**On a managed cloud workspace**, orboto AI works out of the box: nothing
to paste, nothing to sign up for elsewhere. Usage is billed pay-as-you-go
from your workspace's wallet, as part of your subscription - see
[Usage and limits](/orboto-ai/usage-and-limits) for how that's
tracked and what happens if you use more than your plan includes.

**On a self-hosted instance**, there is no automatic wiring - self-hosting
means you run the application yourself, and orboto has no standing
connection into your instance to provide one. You can still use orboto AI:
open **Admin -> AI settings**, pick the orboto AI card, and paste a key
from your own orboto.io account (get one at
[orboto.io](https://orboto.io)). From that point it behaves exactly like
the managed case - one key, no base URL or model wiring to figure out -
except you fetched the key yourself instead of it being provisioned for
you. This is really the same mechanism as connecting any other provider
(see [Bring your own provider](/orboto-ai/byo-keys)); orboto simply
happens to be one of the vendors on the list.

## Turning it on or off [#turning-it-on-or-off]

Every workspace - cloud or self-hosted - has three choices for the chat
provider, and (independently) for the embeddings provider: **orboto AI**,
**your own provider**, or **disabled**. Switching between them is
lossless: the settings for whichever provider you switch away from are
kept, so switching back later restores them instead of making you
re-enter everything.

The full click-by-click walkthrough, including the embeddings subsection
and per-feature model overrides, lives in
[AI providers and models](/admin/ai/ai).

## Troubleshooting [#troubleshooting]

* **I don't see a way to change the AI provider.** Only a super-admin or a
  user with the `admin:ai:write` permission can change it. Ask a
  workspace admin to either make the change or grant you that permission.
* **AI features are off entirely.** Someone chose the **Disabled** card in
  **Admin -> AI settings**. Pick orboto AI or your own provider to turn
  features back on.
* **Chat works but search/Ask-Docs/duplicate detection doesn't (or vice
  versa).** Chat and embeddings are separate provider choices - check both
  sections in **Admin -> AI settings**, not just one.
* **AI features stopped working and nothing was changed in the UI.**
  On a managed workspace this is usually the metered allowance, not a
  configuration problem - see
  [Usage and limits](/orboto-ai/usage-and-limits) for what a paused
  state looks like and how to resolve it.


# Usage and limits (/orboto-ai/usage-and-limits)



orboto AI (see [what it is](/orboto-ai)) is metered: each call to a
model costs a small amount based on how much text goes in and comes out.
Your subscription includes a monthly allowance of that spend, and your
orboto account controls what happens once you use it up. This page
explains the mechanics; it deliberately doesn't quote figures - your
plan's actual allowance, and any price for going beyond it, are shown in
your orboto account, not here.

This page applies when **orboto AI** is the active provider (chat,
embeddings, or both). If you're using your own provider account instead,
its usage and billing are entirely between you and that provider - see
[Bring your own provider](/orboto-ai/byo-keys).

## Where consumption is tracked [#where-consumption-is-tracked]

Two different views, for two different questions:

* **"How much of my included AI have I used?"** - **Admin -> AI
  settings** shows an **orboto AI - included usage & wallet** card once
  billing data has reached your workspace: this month's included allowance
  consumed so far, whether overage is on, and your wallet balance. A
  **Manage** link opens your orboto account for the full, authoritative
  picture and to change any of these settings.

  {/* screenshot: AI settings page, the "orboto AI - included usage & wallet" card */}

* **"What is actually generating that usage?"** - **Admin -> AI Usage**
  (documented in [AI providers and models](/admin/ai/ai#ai-usage))
  reports call counts, input/output tokens, errors, a daily chart, and
  per-user and per-operation breakdowns. It doesn't show currency figures,
  but it's the place to see which feature, project or teammate is driving
  consumption - useful context before you decide whether to raise a
  per-feature answer-length budget, restrict a costly feature, or just
  accept the usage.

## How the allowance is spent down [#how-the-allowance-is-spent-down]

Your workspace draws on three things, in this order, before AI pauses:

1. **The included monthly allowance** that comes with your subscription.
2. **Overage**, if you've turned it on in your orboto account - lets usage
   continue past the included allowance, optionally capped at an amount
   you set.
3. **Your wallet balance**, as a further backstop once overage (if any) is
   also exhausted.

The included allowance resets every month. Overage is off by default,
meaning AI simply pauses once the included allowance runs out rather than
spending anything further; turning it on, and setting or changing its
cap, is done from your orboto account (linked from the **Manage** button
mentioned above).

## What happens when it runs out [#what-happens-when-it-runs-out]

When every step above is exhausted, orboto AI pauses for the workspace
until it's resolved:

* **Interactive features** (AI Chat, summarize, translate, and anything
  else that runs while someone is waiting) fail immediately with a clear
  "AI is paused" message rather than a generic provider error. The message
  is specific to why - included allowance used up, overage cap reached, or
  wallet balance too low - and links to the right place in your orboto
  account to fix it.
* **Background indexing** (the embeddings that power search, duplicate
  detection and Ask-Docs) pauses rather than failing - nothing is lost.
  Content created while paused is simply indexed once AI resumes.
* **Resuming is automatic.** orboto periodically re-checks whether the
  block has cleared, so once you've raised the cap, turned on overage, or
  topped up your wallet, features typically come back within a couple of
  minutes on their own - there's nothing to restart. Failing that, the
  included allowance resets automatically at the start of the next month
  regardless of what you do.

## Troubleshooting [#troubleshooting]

* **The spend card isn't showing at all.** It only renders once your
  orboto account has sent billing data to the workspace; a very recently
  created workspace may not have it yet. Check
  [your orboto account](https://account.orboto.io/ai) directly for the
  authoritative numbers in the meantime.
* **AI is paused and I'm not sure why.** Open **Admin -> AI settings** -
  the banner names the specific reason (allowance, overage cap, or
  wallet) and links straight to the fix.
* **I fixed it in my account but AI is still paused.** Resuming happens on
  the next automatic check, typically within a couple of minutes; if it's
  been longer than that, try the action again - a successful call clears
  the paused state immediately.
* **I want to know what's driving usage before raising a cap.** Check
  **Admin -> AI Usage**'s per-user and per-operation breakdowns first (see
  above) - it's common to find one feature or one heavy user rather than
  needing a blanket increase.


# Backups and destinations (/self-hosting/backups)



This page is the self-hosting angle on backups: shipping your scheduled
jobs to your own external storage, and how the resulting archives restore
onto an instance. For creating a job in the first place - its name, scope
(whole workspace or a single project), cron schedule, and retention
window - see [Backups](/admin/operations/backup) in the admin guide;
that flow is identical whether you're self-hosted or on cloud. This page
picks up from the job form's **destination** field.

Every job (Admin → Backup) can ship its output to the instance's own
storage (the default) or to **your own S3 bucket** - any S3-compatible
service: AWS S3, Cloudflare R2, Backblaze B2, MinIO, Hetzner Object
Storage. Each job also chooses **what** it ships - the content scope
below.

## Content scopes [#content-scopes]

| Scope                  | What lands at the destination                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Database + files       | The classic combined ZIP: every table as NDJSON plus every storage object. Restorable as-is through the setup wizard.                                                                                                    |
| Database only          | The same ZIP without the storage objects - small, fast, ideal for frequent schedules. Pair it with a "Files only" job so the objects are covered too.                                                                    |
| Files only (S3 mirror) | No archive. Every owned storage object (attachments, avatars) is mirrored to `<prefix>/storage/<key>` in your bucket - **incremental** by key + size, nothing is ever deleted on the remote. External destinations only. |

A sensible offsite setup is two jobs against the same bucket: a daily
"Database only" archive plus a daily "Files only" mirror. The mirror
only transfers new/changed objects, so daily runs stay cheap even with
a large attachment history.

## Configuring an external destination [#configuring-an-external-destination]

In the job form, pick **External S3 bucket** and fill in endpoint
(empty for AWS), region, bucket, access key and secret. **Test
connection** verifies the credentials against the bucket before you
save. The secret is encrypted at rest with the instance's key envelope
and is never returned by the API - edit forms show `***`, which keeps
the stored secret unless you type a new one.

{/* screenshot: the backup job form with the External S3 bucket destination fields filled in */}

## Restoring [#restoring]

* An archive in your bucket restores like any other backup: download
  the ZIP and feed it to the setup wizard (**Restore from a backup**) - see
  [First-run setup](/self-hosting/first-run).
* A "Database only" archive plus the mirrored `storage/` prefix
  restore together: import the archive first, then copy the mirrored
  objects into the instance's storage under their original keys (the
  keys under `<prefix>/storage/` ARE the original keys).

## Run results [#run-results]

Every run lands in the run history with the destination path
(`s3://bucket/...`) and, for mirrors, the new/unchanged object counts.
A mirror run fails (and alerts like any failed backup) when any object
could not be transferred.

## Notes [#notes]

* Retention (`retentionDays`) applies to the internal storage cleanup;
  objects in YOUR bucket are yours - manage lifecycle rules there.
* The mirror only ships workspace content (the same owned-keys filter
  the exports use); internal backup archives never leave the instance
  through a mirror.

## Troubleshooting [#troubleshooting]

**Test connection fails when I set up an external destination.**
Cause: wrong endpoint/region for a non-AWS provider, a bucket that doesn't
exist yet, or credentials without write access.
Fix: for a non-AWS S3-compatible service, the endpoint field is required
(only AWS leaves it empty); confirm the bucket exists and the access key
can write to it.

**A scheduled run shows as failed in the run history.**
Cause: for a mirror job, at least one object couldn't be transferred -
usually a transient network error or a credential that expired mid-run.
Fix: open the run's details for the specific object(s) that failed, then
re-run the job; it only needs to (re-)transfer what's missing or changed.

**Restoring a "Database only" archive leaves attachments broken.**
Cause: a database-only archive intentionally excludes storage objects -
you need to also restore the paired "Files only" mirror from the same
bucket.
Fix: after importing the archive, copy the mirrored objects from
`<prefix>/storage/` into the instance's storage under their original keys.


# Deploying with Coolify (/self-hosting/coolify)



[Coolify](https://coolify.io) is a popular self-hosted deployment platform.
If you already run it (or want the simplest possible orboto install), this
is the recommended path: point Coolify at the compose file and it wires
domains, TLS certificates and secrets for you.

Prefer full control, or no platform at all? Use the standalone
[Docker guide](/self-hosting/docker) - everything Coolify automates here is
done by hand there.

## The deploy [#the-deploy]

Coolify auto-populates every `SERVICE_*` magic variable in `docker-compose.yml` (credentials, random DB name, public hostnames) and keeps them stable across rebuilds.

> ⚠️ &#x2A;*Volumes are `external: true`.** The three persistent volumes (`orboto_postgres_data`, `orboto_rustfs_data`, `orboto_backups`) are declared external so Coolify cannot recreate them on redeploy (which would silently wipe the database). **You must create them once on the host before the first deploy** - see the pre-flight step below.

### Pre-flight (first-time setup OR migrating from an older Coolify-managed install) [#pre-flight-first-time-setup-or-migrating-from-an-older-coolify-managed-install]

SSH to the Coolify host and run the migration helper:

```bash
git clone https://github.com/orboto/orboto /tmp/orboto-setup
cd /tmp/orboto-setup
sudo ./scripts/migrate-to-external-volumes.sh          # existing install - copies from Coolify-managed volumes
# or, for a brand-new install that has never deployed yet:
sudo ./scripts/migrate-to-external-volumes.sh --fresh  # creates empty externals, no copy
```

The script refuses to run while any orboto container is up; in Coolify, click **Stop** on the orboto app first, then run it.

After it completes you'll have three named volumes on the host - `orboto_postgres_data`, `orboto_rustfs_data`, `orboto_backups` - that the compose file references. Coolify deploys/redeploys from here on will reuse them.

### Actual deploy [#actual-deploy]

1. **Create a new resource** → Docker Compose → point it at the orboto repository (branch `main`) → select `docker-compose.yml`.
2. **Domains**: Coolify auto-assigns a hostname from your wildcard domain for `SERVICE_FQDN_WEB_80` (the only public FQDN - the `api` is reached via `/api/*` through the web's nginx). Optionally swap in your own custom domain.
3. **Deploy**. Database migrations run automatically on every container start - the API image's entrypoint is `node dist/db/migrate.js && node dist/index.js`, so a redeploy always applies pending migrations before the API accepts traffic. No manual step needed, even on upgrades. If a migration fails the container exits non-zero and Coolify won't route traffic to a half-migrated API.

{/* screenshot: the Coolify "New resource" dialog with Docker Compose selected and the repository pointed at orboto */}

That's it. Open the web FQDN in a browser and the setup wizard will prompt for the first admin account - see [First-run setup](/self-hosting/first-run).

> **Upgrade safety.** Drizzle migrations are idempotent and additive - existing rows keep their values, NOT NULL columns are introduced with `DEFAULT` + backfill `UPDATE` in the same migration. The `pg_backup` sidecar (see below) plus Coolify's volume persistence mean that rolling back a bad deploy only requires redeploying the previous image tag. Before a *major* upgrade or before applying a migration from an unfamiliar branch, take a pre-migrate snapshot manually:
>
> ```bash
> docker compose exec -T postgres pg_dump -U "$SERVICE_USER_POSTGRES" -Fc "$POSTGRES_DB" > pre-migrate-$(date -u +%Y%m%dT%H%M%SZ).dump
> ```

**Post-deploy configuration**:

* **Email delivery** → log in as admin → System Settings → Email delivery. Pick **UseSend** (recommended for EU / DSGVO - paste an API key from your UseSend admin UI plus the base URL; self-hostable via Docker / Coolify with AWS SES `eu-central-1` underneath), **Resend** (paste an API key from [resend.com](https://resend.com/api-keys)), or **SMTP** (host/port/credentials). Click "Send test" to verify.
* `SENTRY_DSN` (Coolify env tab) - ships unhandled exceptions to Sentry
* `IMAGE_TAG` (Coolify env tab) - pin to a specific git SHA instead of `latest`
* `LOG_LEVEL`, `RATE_LIMIT_MAX`, `S3_BUCKET`, `S3_REGION`, `PG_BACKUP_RETENTION_DAYS` (Coolify env tab) - overrides for the shipped defaults

On redeploy, volumes and auto-generated secrets are preserved. To rotate a secret (e.g. `SERVICE_PASSWORD_64_JWT`), clear the value in Coolify and the next deploy regenerates it - note that rotating `JWT_SECRET` invalidates all sessions and rotating `GIT_ENC_SECRET` makes existing encrypted git tokens unreadable.

{/* screenshot: the Coolify environment variables tab for the orboto resource */}

## Troubleshooting [#troubleshooting]

**My database is empty after a redeploy.**
Cause: the persistent volumes weren't created as `external` before the
first deploy, so Coolify recreated them from scratch.
Fix: this should not happen if you ran the pre-flight step above first.
If it already has, restore from a backup - see [Backups](/self-hosting/backups).
Going forward, always run the pre-flight migration helper before the very
first deploy on a Coolify host.

**Deploy succeeds but the app shows a blank page or a CORS error.**
Cause: the API and web hostnames don't match what the containers were
built/configured with.
Fix: confirm `SERVICE_FQDN_WEB_80` and `SERVICE_URL_API` in the Coolify
env tab match the domain you're actually opening in the browser, then
redeploy.

**A deploy exits non-zero right after "running migrations".**
Cause: a pending migration failed - Coolify intentionally won't route
traffic to a half-migrated API.
Fix: check the deployment logs for the actual database error. The
previous, working deployment stays live until you fix it and redeploy.

**I rotated a secret and now nobody can sign in, or git connections stopped working.**
Cause: rotating `JWT_SECRET` invalidates every session by design; rotating
`GIT_ENC_SECRET` makes existing encrypted git access tokens unreadable by
design.
Fix: for `JWT_SECRET`, everyone simply signs in again - expected. For
`GIT_ENC_SECRET`, re-create each git connection with a fresh access token.


# Self-hosting with Docker (/self-hosting/docker)



orboto self-hosts on **any machine that runs Docker** - a VPS, a homelab
box, bare metal. This guide is fully standalone: plain Docker Compose, your
own reverse proxy, no deployment platform required.

> Running [Coolify](https://coolify.io)? There is a dedicated
> [one-click path](/self-hosting/coolify) that automates most of the
> steps below. This page is the reference for everyone else - and for
> understanding what the one-click path does under the hood.

You have two paths:

* **Coolify** (recommended if you have it) - Coolify auto-generates all
  secrets, hostnames, and named volumes for you. Jump to the
  [Coolify guide](/self-hosting/coolify).
* **Manual VPS** - classic Docker + reverse proxy, below.

Every variable referenced here ships with an inline comment in the compose
file itself, and the full reference lives in `docs/env.md` in the repo.

## Before you start [#before-you-start]

* Linux with Docker ≥ 24 and Docker Compose v2.
* DNS `A` records for **both** your web hostname (e.g. `orboto.example.com`)
  and your API hostname (e.g. `api.orboto.example.com`) pointing at the
  host - or a single wildcard record.
* Ports `80` and `443` open on the firewall. The API and web containers are
  NOT bound to public ports themselves - only your reverse proxy is.

## 1. Get the files and set your secrets [#1-get-the-files-and-set-your-secrets]

```bash
git clone https://github.com/orboto/orboto.git /opt/orboto
cd /opt/orboto
cp .env.prod.example .env.prod
```

Fill in `.env.prod`, generating strong secrets:

```bash
openssl rand -hex 32   # for SERVICE_PASSWORD_64_JWT and SERVICE_PASSWORD_64_GIT
openssl rand -hex 16   # for SERVICE_PASSWORD_POSTGRES and SERVICE_PASSWORD_RUSTFS
```

`JWT_SECRET`, `GIT_ENC_SECRET`, and `SSO_ENC_SECRET` are **required** in
production - the API refuses to boot without them, so it can never run on a
public host with the (openly documented) development fallback values.

## 2. What happens on the first boot [#2-what-happens-on-the-first-boot]

Before the API applies any pending database migration, it automatically
snapshots your database (`pg_dump`) and streams it to your own S3-compatible
storage under `system/pre-migrate/`. If the snapshot fails, the boot aborts
and **no migration runs** - your previous deployment stays live. This is
on by default and needs no setup; the compose file also ships a `pg_backup`
sidecar that takes an hourly raw dump as a second safety net.

| Var                         | Default | Purpose                                                        |
| --------------------------- | ------- | -------------------------------------------------------------- |
| `PRE_MIGRATE_SNAPSHOT`      | on      | Set to `off` to skip the automatic snapshot (not recommended). |
| `PRE_MIGRATE_SNAPSHOT_KEEP` | `5`     | How many snapshots to keep.                                    |
| `PG_BACKUP_RETENTION_DAYS`  | `14`    | How long the hourly sidecar dumps are kept.                    |

## 3. Build and start [#3-build-and-start]

```bash
docker compose --env-file .env.prod build
docker compose --env-file .env.prod up -d
```

The API container migrates the database automatically before it starts
serving traffic, on every `up` - including upgrades, so there is no manual
migration step. Check it came up:

```bash
curl -f http://localhost:3000/ready   # from inside the host; the API is not bound publicly
```

## 4. Put a reverse proxy in front [#4-put-a-reverse-proxy-in-front]

Whichever proxy you use, it needs to route four kinds of request to the
right container and nowhere else: `/api/*` and `/git/webhook/*` to the API,
WebSocket upgrades on `/ws*` to the API, `/mcp` to the MCP container if
you run one, and everything else - the SPA itself - to the web container.

### Caddy (simplest - automatic TLS) [#caddy-simplest---automatic-tls]

1. Install Caddy: [caddyserver.com/docs/install](https://caddyserver.com/docs/install)
2. Create `/etc/caddy/Caddyfile`, replacing `orboto.example.com` with your
   hostname:

   ```
   orboto.example.com {
     encode gzip zstd

     header {
       Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
       X-Frame-Options "DENY"
       X-Content-Type-Options "nosniff"
       Referrer-Policy "strict-origin-when-cross-origin"
     }

     @websocket {
       header Connection *Upgrade*
       header Upgrade websocket
       path /ws*
     }
     reverse_proxy @websocket api:3000

     reverse_proxy /api/* api:3000
     reverse_proxy /git/webhook/* api:3000

     # MCP clients (Claude Desktop, Cursor, ...) - only needed if you run the mcp service
     reverse_proxy /mcp mcp:3100 {
       flush_interval -1
     }

     reverse_proxy web:80
   }
   ```
3. `sudo systemctl reload caddy` (or `caddy reload` if you run it directly, not as a service). Caddy obtains and renews the TLS certificate automatically - nothing else to configure.

### Traefik [#traefik]

Add this as a dynamic-config file, or transcribe the equivalent labels
directly onto the `api`/`web`/`mcp` compose services:

```yaml
http:
  routers:
    orboto-api:
      rule: "Host(`orboto.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/git/webhook`) || PathPrefix(`/ws`))"
      entryPoints: [websecure]
      service: orboto-api
      tls: { certResolver: letsencrypt }
      middlewares: [orboto-strip-api, orboto-security-headers]
    orboto-mcp:
      rule: "Host(`orboto.example.com`) && PathPrefix(`/mcp`)"
      entryPoints: [websecure]
      service: orboto-mcp
      priority: 100
      tls: { certResolver: letsencrypt }
      middlewares: [orboto-security-headers]
    orboto-web:
      rule: "Host(`orboto.example.com`)"
      entryPoints: [websecure]
      service: orboto-web
      tls: { certResolver: letsencrypt }
      middlewares: [orboto-security-headers]
  middlewares:
    orboto-strip-api:
      stripPrefix: { prefixes: ["/api"] }
    orboto-security-headers:
      headers:
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        frameDeny: true
        contentTypeNosniff: true
        referrerPolicy: "strict-origin-when-cross-origin"
  services:
    orboto-api:
      loadBalancer: { servers: [{ url: "http://api:3000" }] }
    orboto-mcp:
      loadBalancer: { servers: [{ url: "http://mcp:3100" }] }
    orboto-web:
      loadBalancer: { servers: [{ url: "http://web:80" }] }
```

The `orboto-mcp` router has a higher `priority` so it matches before the
catch-all `orboto-web` router - without it, every request would fall
through to the SPA instead of reaching the MCP container. Drop the
`orboto-mcp` router and service entirely if you don't run the `mcp`
service.

### Security headers [#security-headers]

The shipped web container already sets `Content-Security-Policy`,
`X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, and
`Permissions-Policy` on its own responses - the header blocks in both
samples above add HSTS on top (HSTS has to live at the TLS-terminating
edge, which the container itself isn't). If you front the SPA with a proxy
that isn't the shipped nginx, replicate the container's header set too.

### Receiving mail directly (optional) [#receiving-mail-directly-optional]

If you want orboto to receive inbound mail on port 25 instead of a webhook
provider, your reverse proxy needs a TCP/stream block in addition to the
HTTP routes above - see [inbound email](/admin/email/inbound-email)
for the DNS and TLS walkthrough.

## 5. Finish setup [#5-finish-setup]

Open your web hostname in a browser. See [First-run setup](/self-hosting/first-run)
for the setup wizard - creating the admin account or restoring a backup.

Want customer-facing invitations on a separate brand domain? See
[Multiple domains](/self-hosting/multi-domain).

## 6. Day-to-day operations [#6-day-to-day-operations]

* **Upgrading** - see [Upgrades](/self-hosting/upgrades).
* **Logs** - `docker compose logs -f api` (JSON; auth headers and passwords are redacted automatically).
* **Health** - `/health` is a pure liveness probe. `/ready` checks Postgres + storage and returns `503` on failure. See [Monitoring](/self-hosting/monitoring) for what to hook a monitor up to.
* **Rate limits** - `600`/min per IP by default, `20`/min on auth, setup, and invitation routes. Tune with `RATE_LIMIT_MAX`.
* **Backups** - see [Backups](/self-hosting/backups) for the in-app scheduler; keep the `pg_backup` sidecar running alongside it.
* **Audit log** - entries older than a year are pruned automatically; adjust `audit_log_retention_days` in system settings if you need a different window.

## 7. Connecting AI clients (MCP) [#7-connecting-ai-clients-mcp]

The shipped compose file includes an `mcp` service so Claude Desktop,
Cursor, and other MCP-aware clients can talk to your instance natively.
Bring it up alongside the rest:

```bash
docker compose --env-file .env.prod up -d mcp
```

You do **not** need a separate hostname or DNS record for it: route `/mcp`
through your existing reverse-proxy config exactly like `/api` and `/ws`
above (the Caddy and Traefik samples already include it) - operators then
connect at `https://orboto.example.com/mcp`, one URL, one certificate,
alongside the rest of your deployment. A dedicated `mcp.<your-host>`
subdomain is still supported if a particular client needs it, but it's an
opt-in extra, not the default path.

The per-client setup - which API-key scope to mint, where each client
expects its config, and the identity/consent model when a client connects
via OAuth - is in [Connect an AI client](/agents-ai/mcp). Skip this
whole section if your team doesn't use MCP clients.

## Running on a different CPU architecture [#running-on-a-different-cpu-architecture]

orboto's images are published for both `linux/amd64` and `linux/arm64`, so
the same image tag runs on an Intel/AMD VPS, an ARM VPS, or Apple-silicon
hardware - Docker picks the right one automatically, no compose changes
needed. Building your own image for a private registry works the same way
with `docker buildx build --platform linux/amd64,linux/arm64 ...`.

## Scaling beyond one process (optional) [#scaling-beyond-one-process-optional]

The default deploy runs a single `api` container that serves HTTP **and**
runs all background jobs (`API_ROLE=all`). Most installs never need to
change this.

**More HTTP throughput.** Run several `api` containers with `API_ROLE=api`
(HTTP only) plus exactly **one** dedicated worker (`command: node dist/worker.js`,
`API_ROLE=worker`) that owns the background jobs - cron schedules, the
embedding backlog, and so on must fire from exactly one process. The
compose file ships a profile-gated `worker` service for this:

```bash
API_ROLE=api docker compose --env-file .env.prod up -d api web
docker compose --env-file .env.prod --profile worker up -d worker
```

**All cores of one box, no extra container.** Set `API_WORKERS=N` and the
`api` process becomes a small cluster primary that forks `N` workers
sharing the listen socket. Slot 0 keeps the background jobs; the rest serve
HTTP only. Defaults to `1` (unchanged behaviour) - this is an explicit
opt-in, not automatic:

```bash
API_WORKERS=14 docker compose --env-file .env.prod up -d api web
```

Each worker opens its own database connection pool (`DB_POOL_MAX`, default
`10`), so size it against Postgres's `max_connections` (raised to `200` in
the shipped compose file):

```
N_workers × DB_POOL_MAX  +  N_workers × 1 (LISTEN)  +  ~5 (background)  +  margin  <  max_connections
```

On a big box, lower `DB_POOL_MAX` as you raise `API_WORKERS` rather than
letting the total run away.

**Tuning Postgres for the box.** The database container ships with stock,
small-box defaults so an image pull never silently re-tunes a running
instance. Size these to your box's RAM if you're running a dedicated box:

| Box RAM | `PG_SHARED_BUFFERS` | `PG_EFFECTIVE_CACHE_SIZE` | `PG_WORK_MEM` | `PG_MAINTENANCE_WORK_MEM` |
| ------- | ------------------- | ------------------------- | ------------- | ------------------------- |
| 2 GB    | `512MB`             | `1280MB`                  | `8MB`         | `128MB`                   |
| 4 GB    | `1GB`               | `3GB`                     | `16MB`        | `256MB`                   |
| 8 GB    | `2GB`               | `5GB`                     | `24MB`        | `512MB`                   |
| 16 GB   | `4GB`               | `11GB`                    | `32MB`        | `1GB`                     |

On SSD-backed storage also set `PG_RANDOM_PAGE_COST=1.1` - the Postgres
default of `4.0` assumes a spinning disk and discourages index scans.

## Troubleshooting [#troubleshooting]

**The API container keeps restarting instead of coming up.**
Cause: the automatic pre-migrate snapshot failed - usually bad S3
credentials, `pg_dump` missing, or the database being unreachable.
Fix: run `docker compose logs api` and look for a line starting
`[migrate] FATAL` - it names the actual cause. Fix that, or set
`PRE_MIGRATE_SNAPSHOT=off` to skip the safety net (not recommended).

**Nothing loads in the browser at all.**
Cause: DNS isn't pointing at the host yet, or ports `80`/`443` are closed.
Fix: verify your `A` records and firewall rules match [Before you start](#before-you-start).

**`curl .../ready` returns `503`.**
Cause: Postgres or the S3-compatible storage isn't reachable from the API
container.
Fix: confirm those containers are healthy and that `DATABASE_URL` /
`S3_*` point at them correctly.

**Invitations and notifications never arrive by email.**
Cause: no email provider is configured yet - this is deliberately not an
env var.
Fix: sign in as admin → **System Settings → Email delivery**, pick a
provider, and use **Send test**.


# First-run setup (/self-hosting/first-run)



The first time you open a fresh orboto instance you land in the setup
wizard. It only appears while the instance is uninitialized, and it offers
three starting points.

{/* screenshot: the setup wizard's choice screen with all three options */}

## The setup token [#the-setup-token]

Two of the three paths below (restore, and import from another instance)
ask for a **setup token** - a one-time secret that proves you're the
operator of this specific machine, not a random visitor who reached your
fresh instance before you did. You don't need it for a brand-new fresh
workspace, only for restore and import.

Where to find it:

* If you set the `SETUP_TOKEN` environment variable yourself, that's the
  token - it doesn't change between restarts.
* Otherwise, orboto generates one automatically and prints it once to the
  container's boot log, in a boxed banner. Read it with
  `docker compose logs api` (or your platform's log viewer) right after
  first boot. It regenerates on every process restart if you never set
  `SETUP_TOKEN`, so if you missed it, restart the container and read the
  log again before you start the wizard.

The token is never returned by any API response - it only ever reaches you
through the log. It stops being needed the moment setup completes.

## Option 1: Fresh workspace [#option-1-fresh-workspace]

Two steps, then you're in.

**Step 1 - workspace basics.**

* **Workspace name** - shown in the browser tab and in outgoing email
  templates. Required.
* **Workspace language** - the initial UI language for the admin account
  you're about to create, and the language used for default email
  templates. Individual users can still pick their own display language
  later, once they're in - this only sets the starting point.
* **Workspace timezone** - pre-filled from your browser, but editable.
  This is not a display preference: it's the single timezone your
  scheduled jobs (backups, reminders, cron-based alerts) are anchored to.
  Get this right if your server runs in a different zone than the browser
  you're setting it up from - individual users set their own display
  timezone separately, later, in their profile.

**Step 2 - the administrator account.** Your name, email, and password.
This becomes the first user in the workspace, with full administrator
access.

{/* screenshot: the setup wizard's workspace-basics step with name, language and timezone fields */}

Submit, and you're signed in immediately. The admin **configuration
wizard** then walks you through the common areas (email, AI, integrations)
inside the app at your own pace - none of it blocks you from using orboto
right away.

## Option 2: Restore from a backup [#option-2-restore-from-a-backup]

Choose this to move an existing workspace onto this instance from a backup
archive you already have - see [Backups](/self-hosting/backups) for
how archives are produced.

1. Enter the **setup token** for this instance (see above).
2. Select or drag in the archive file (`.zip`).
3. Select **Start restore**.

{/* screenshot: the restore step with the setup-token field and the archive file picker */}

The instance restores every user, project, and file from the archive, then
shows a summary: how many rows across how many tables, and how many
storage objects (attachments, avatars, and so on) came along. If anything
in the archive couldn't be applied cleanly, it's listed as a warning below
the summary rather than silently dropped - read those before you continue.
Select **Go to sign in** and use the credentials from the backup - not new
ones, the account you restored already exists with its original password.

## Option 3: Import from another orboto instance [#option-3-import-from-another-orboto-instance]

Choose this to pull a complete, running workspace directly from another
live orboto instance - including its attachments - without producing an
intermediate archive file yourself. Useful for moving from orboto cloud to
self-hosted, or between two self-hosted instances, without a manual
export/download/upload round-trip.

You need two tokens from two different places:

1. **On the source instance** (the one you're moving *from*), sign in as
   an admin and go to **Admin → Backup → Migration export access**, and
   create an export token there (it looks like `orbexp_…`). This is a
   separate credential from your account password, scoped only to this
   migration.
2. **On this instance** (the fresh one you're setting up), gather the
   **setup token** as described above.

Then, in the wizard:

* **Source instance URL** - the full address of the instance you're
  importing from (for example `https://old.example.com`).
* **Export token** - the `orbexp_…` token from step 1.
* **Setup token** - this instance's own setup token from step 2.

{/* screenshot: the import-from-another-instance form with source URL, export token and setup token fields */}

Select **Start import**. This can take a while for a large workspace - it
pulls the full database export and then transfers every storage object
(attachments, avatars) one by one. If some files fail to transfer (a
network blip, a temporary permission issue), the result screen tells you
how many and offers **Retry missing files**, which only re-attempts what's
still missing rather than starting over. Once it's done, sign in with the
credentials from the old instance - everything came along, including
passwords.

## Notes [#notes]

* The wizard is rate-limited and disabled the moment setup completes -
  it can never be re-run against a live instance, by any of the three
  paths.
* If the instance shows the normal sign-in screen instead of the wizard,
  it is already initialized.

## Troubleshooting [#troubleshooting]

**The wizard rejects my setup token as "invalid or missing".**
Cause: you typed it wrong, it regenerated on a restart because
`SETUP_TOKEN` was never pinned in your environment, or setup already
completed on this instance (the token stops being checked afterwards).
Fix: re-read the current token from the boot log (`docker compose logs
api`), or set `SETUP_TOKEN` explicitly in your environment so it stops
changing between restarts.

**I reach the wizard again after setup already completed.**
Cause: this shouldn't happen on a genuinely initialized instance - you are
more likely looking at a *different* instance (a fresh container, or a
database that was reset) than the one you set up before.
Fix: confirm you're pointed at the right hostname and the right database
before restoring or importing anything, so you don't overwrite an existing
workspace.

**The restore step rejects my backup archive.**
Cause: the archive is corrupted, from an incompatible version, or the
upload was interrupted.
Fix: re-download the archive from its original source and try again; see
[Backups](/self-hosting/backups) for how archives are produced.

**The remote import fails immediately with a connection error.**
Cause: the source instance URL is unreachable from this server (typo,
firewall, or the source instance is actually down), or the export token
was already used up or revoked on the source side.
Fix: confirm you can reach the source URL from this host, and generate a
fresh export token from the source instance's **Admin → Backup →
Migration export access** if you're unsure the old one is still valid.

**I can't reach the wizard at all - it goes straight to a sign-in screen.**
Cause: the instance is already initialized (`setup_completed` is set).
Fix: sign in normally, or restore/import into a fresh database if you
intended to start over.


# Self-hosting (/self-hosting)



orboto is self-hostable by design: three containers (`api`, web, `mcp`) plus
PostgreSQL and an S3-compatible object store, shipped as multi-arch images.
If you prefer not to operate it yourself, orboto cloud runs the same
product fully managed.

<Cards>
  <Card title="Self-hosting with Docker" href="/self-hosting/docker" description="The standalone reference: Compose, reverse proxy, operations, scaling." />

  <Card title="Deploying with Coolify" href="/self-hosting/coolify" description="The easy way - one-click deploy on the Coolify platform." />

  <Card title="First-run setup" href="/self-hosting/first-run" description="The setup wizard: create the admin account or restore a backup." />

  <Card title="Upgrades" href="/self-hosting/upgrades" description="Move an instance to a new version safely, and roll back if needed." />

  <Card title="Multiple domains" href="/self-hosting/multi-domain" description="Serve one workspace under several hostnames." />

  <Card title="Backups" href="/self-hosting/backups" description="Scheduled backups, destinations, restore paths." />

  <Card title="Monitoring" href="/self-hosting/monitoring" description="Health endpoints, metrics, and log expectations." />
</Cards>

## Troubleshooting [#troubleshooting]

**I'm not sure whether to self-host or use orboto cloud.**
Self-hosting gives you full infrastructure control - your own network,
region, and scaling decisions - at the cost of running Docker yourself.
See [orboto cloud](/cloud) for the fully managed alternative; every
feature is identical either way.


# Monitoring and health checks (/self-hosting/monitoring)



This page covers what your own monitoring stack needs to watch a
self-hosted orboto instance: the two health endpoints, the metrics
endpoint, and log behaviour. It applies to self-hosted installs - on
orboto cloud, monitoring is the platform's job.

## Health endpoints [#health-endpoints]

| Endpoint      | Checks                                                                                  | Use it for                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `GET /health` | The process is up. Nothing else.                                                        | Container liveness - restart the container if this stops responding.                                                   |
| `GET /ready`  | Postgres and your S3-compatible storage are reachable. Returns `503` if either is down. | Container readiness - don't route traffic here until this is `200`. Also a good target for an external uptime monitor. |

Point your orchestrator's liveness probe at `/health` and its readiness
probe at `/ready`. If you don't run an orchestrator, an external uptime
monitor hitting `/health` on an interval is enough to know the process is
alive; hit `/ready` as well if you want to be alerted specifically on a
database or storage outage rather than a process crash.

Sanity-check both from the host right after you deploy:

```bash
curl -i https://your-domain.example.com/health   # expect: 200, body {"status":"ok"}
curl -i https://your-domain.example.com/ready    # expect: 200 once Postgres + storage are reachable
```

**No monitoring stack yet?** You don't need Prometheus to get basic
coverage. Any free or paid external uptime-check service (the kind that
just polls a URL on an interval and emails/pages you on failure) works
fine pointed at `/health` - that alone catches "the whole instance is
down", which is most of what actually goes wrong on a small deployment.
Add `/ready` as a second check once you want to distinguish "the process
crashed" from "the database is unreachable but the process is still up".

## Metrics [#metrics]

`GET /metrics` exposes Prometheus-format metrics: process and HTTP-request
metrics plus a handful of orboto-specific counters. It is **gated** in
production so it never leaks route topology or request volume publicly -
one of these must be set, or the endpoint returns `503`:

* `METRICS_ALLOWED_CIDRS` - comma-separated CIDR allowlist (IPv4 and IPv6),
  e.g. `10.0.0.0/8,127.0.0.1/32`, so your Prometheus host can scrape it.
* `METRICS_BASIC_AUTH` - `user:pass`; the scraper sends HTTP Basic auth.

In development, with both unset, `/metrics` is open on localhost.

```yaml
# prometheus.yml
scrape_configs:
  - job_name: orboto-api
    metrics_path: /metrics
    # If you use METRICS_BASIC_AUTH instead of a CIDR allowlist:
    # basic_auth: { username: prom, password: <pass> }
    static_configs:
      - targets: ["orboto-api:3000"]
```

Metrics worth alerting on:

| Metric                                                         | Meaning                                                                |
| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `http_request_duration_seconds_bucket`                         | HTTP latency histogram (per route/method/status) - drives p50/p95/p99. |
| `http_request_duration_seconds_count`                          | Request rate; filter `status_code=~"5.."` for the error rate.          |
| `orboto_job_queue_size`                                        | Background job count by state - queue depth.                           |
| `nodejs_eventloop_lag_p99_seconds`                             | Event-loop lag - the canary for a saturated process.                   |
| `nodejs_heap_size_used_bytes`, `process_resident_memory_bytes` | Memory.                                                                |
| `process_cpu_seconds_total`                                    | CPU (rate it for the number of cores in use).                          |

Any Prometheus-compatible dashboard tool can visualise these once scraping
works - point it at the same Prometheus data source you configured above.

## Logs [#logs]

The API logs structured JSON (via Pino). Authorization headers and
passwords are redacted automatically before a line is written, so logs are
safe to ship to a third-party aggregator. Control verbosity with
`LOG_LEVEL` (`info` in production, `debug` in development).

```bash
docker compose logs -f api
```

## Error tracking (optional) [#error-tracking-optional]

Set `SENTRY_DSN` on the API service to start shipping unhandled API
exceptions and frontend crashes to a Sentry-compatible error tracker. The
web bundle picks up the same DSN automatically. Leaving it unset simply
turns this integration off - orboto's own in-app error log for
administrators keeps working either way.

## Troubleshooting [#troubleshooting]

**`/metrics` always returns `503`.**
Cause: in production, neither `METRICS_ALLOWED_CIDRS` nor `METRICS_BASIC_AUTH`
is set - the endpoint refuses to serve anyone.
Fix: set one of the two.

**My Prometheus host gets `401` or `403` from `/metrics`.**
Cause: its IP isn't inside `METRICS_ALLOWED_CIDRS`, or the Basic Auth
credentials don't match `METRICS_BASIC_AUTH`.
Fix: widen the CIDR to include the scraper's real source IP, or fix the
credentials on either side.

**`/ready` flaps between `200` and `503`.**
Cause: Postgres or the S3-compatible storage is intermittently unreachable
from the API container - a network issue, not an application bug.
Fix: check the health of those two services and the network path between
them and the API container.

**Nothing shows up in my error tracker.**
Cause: `SENTRY_DSN` isn't set.
Fix: set it on the API service; it takes effect on the next restart.


# Multiple domains (/self-hosting/multi-domain)



Run orboto on more than one public domain - typically because you want **customer-facing invitations to use a separate brand domain** while the workspace itself stays under your internal one. Example: workspace lives at `orboto.example.internal`, but every invitation email a customer receives points at `kunden.example.com`.

Three places to touch. Order matters.

## 1. Coolify - add the second domain + extend `WEB_ORIGIN` [#1-coolify---add-the-second-domain--extend-web_origin]

Add the customer-facing hostname (e.g. `kunden.example.com`) to your API service in Coolify so its reverse proxy routes the second domain to the same container. TLS is automatic.

Then extend the `WEB_ORIGIN` env var on the API service to list BOTH hostnames:

```
WEB_ORIGIN=https://kunden.example.com,https://orboto.example.internal
```

Two rules to know:

* **Order matters.** orboto builds every outbound email link (invitations, password resets, alerts) from the **first entry** of the comma list. List the customer-facing domain first if you want invitation links to land there.
* **All listed entries are CORS-allowed.** Both domains keep working for the web app + the REST API.

Restart the API container so the new `process.env` value is picked up. Coolify's "Redeploy" button is enough.

## 2. Email From-address - Admin Settings, not env [#2-email-from-address---admin-settings-not-env]

The From-address of outbound mail lives in `system_config` (DB-backed), not in env. Set it through the admin UI so it matches the customer-facing domain:

* **Admin → System Settings → Email**
* For OMS / Resend: change the **From** field (e.g. `einladung@kunden.example.com`)
* For SMTP: change the **SMTP From** field

Cache: the EmailService memoises the sender config for \~60 seconds, so a fresh send within that window still uses the old From. Either wait the minute or restart the API container.

## 3. DNS at the email provider [#3-dns-at-the-email-provider]

For the new domain's emails to actually deliver (and not land in spam), you need the standard outbound-mail records:

| Record                                    | Why                                                                                                                                                             |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SPF** (TXT)                             | Authorises your mail provider to send from `kunden.example.com`. Provider-specific value - OMS / Resend / SMTP provider give the exact string in their console. |
| **DKIM** (CNAME or TXT)                   | Cryptographic signature so recipients can verify the mail came from your provider. Provider-specific too; usually a couple of CNAMEs.                           |
| **DMARC** (TXT, optional but recommended) | Tells receivers what to do with mail that fails SPF / DKIM. Start with `p=none` to monitor, tighten later.                                                      |

Where to set the records depends on your mail provider:

* **OMS** (orboto Mail Service): Customer Portal → Domains → "Add domain" → `kunden.example.com` → Portal shows the exact CNAMEs to paste at your DNS host.
* **Resend**: Dashboard → Domains → Add domain → same flow.
* **SMTP provider** (SES, Mailgun, …): each has its own DNS-records page; the same SPF + DKIM concept applies.

Skipping this step is the most common cause of "invitations arrive but say 'via amazonses.com'" - which usually drops them in junk and erodes the brand.

## Verification [#verification]

After the three steps above:

1. Generate a test invitation from the admin UI.
2. Open the email:
   * **From** matches the new domain (e.g. `einladung@kunden.example.com`)
   * **Link in the body** points at `https://kunden.example.com/...` - NOT the internal domain
3. Select the link → the accept-invitation page loads on the customer-facing domain.

{/* screenshot: an invitation email with the From address and link both on the customer-facing domain */}

## Troubleshooting [#troubleshooting]

**The From address is right, but the link in the email still points at the old domain.**
Cause: either the customer domain is listed second (not first) in the
`WEB_ORIGIN` comma-list, or the API container hasn't picked up the change
yet.
Fix: put the customer-facing domain first in `WEB_ORIGIN`, then restart
the API container (redeploy, on Coolify).

**The link is right, but the From address is still the old one.**
Cause: the email sender config is cached for about 60 seconds after a
save, or the From field wasn't actually saved.
Fix: wait a minute and resend the test, or re-check
**Admin → System Settings → Email** to confirm it saved.

**Neither field updates, and no invitation email arrives at all.**
Cause: `WEB_ORIGIN` resolves to a loopback or internal-only address (a
comma-list starting with `localhost`, a bare IP, `*.local`, or
`*.internal`) - orboto deliberately suppresses invitation links rather than
send a broken one.
Fix: put a real public hostname first in the `WEB_ORIGIN` list.

## Why this setup makes sense [#why-this-setup-makes-sense]

The same orboto workspace can present multiple brands. Internal team uses the workspace at the internal hostname (intranet bookmark, SSO redirect, etc.). External invitees see a branded customer-facing URL with matching email From - feels like a dedicated customer portal, no rebrand confusion.

It is the same workspace under the hood: one database, one set of users, one set of permissions. Only the URL the recipient sees and the From-address on the mail change.

## Related [#related]

* [Self-hosting with Docker](/self-hosting/docker) - first-time deploy walkthrough
* [Backups](/self-hosting/backups) - what a restored archive carries with it, including domain settings


# Upgrades (/self-hosting/upgrades)



orboto releases are shipped as versioned container images. This page
walks through an upgrade end to end, for both a manual Docker Compose
deploy and a Coolify-managed one, then covers rolling back if it goes
wrong.

## Before you start: why this is safe [#before-you-start-why-this-is-safe]

Database migrations that ship with a new version are **additive and
idempotent** - existing rows keep their values, and a new required column
is introduced with a default plus a backfill in the same migration, never
by rejecting old rows. On top of that, the API automatically snapshots
your database with `pg_dump` immediately before it applies any pending
migration, and refuses to apply the migration at all if that snapshot
fails - see [pre-migrate snapshot](/self-hosting/docker#2-what-happens-on-the-first-boot)
for exactly how. In practice this means a routine upgrade is low-risk by
default, and you always have a fresh restore point even if you forget to
take one yourself.

## 1. Back up first [#1-back-up-first]

Trigger a backup run (or confirm last night's succeeded) so you have a
restore point that isn't only the automatic migration snapshot - see
[Backups](/self-hosting/backups). This step is about your own
peace of mind on top of the automatic snapshot, not a substitute for it.

## 2. Update the image tag [#2-update-the-image-tag]

**Manual Docker Compose:**

```bash
cd /opt/orboto
git pull
docker compose --env-file .env.prod pull
docker compose --env-file .env.prod up -d
```

If you pin an explicit `IMAGE_TAG` in `.env.prod` instead of tracking
`latest`, update that value first, then run the same `pull` / `up -d`
pair.

**Coolify:** open the orboto resource → set `IMAGE_TAG` in the environment
variables tab to the new version (or leave it as `latest` to always track
the newest release) → select **Redeploy**.

## 3. Migrations run automatically [#3-migrations-run-automatically]

Either path above re-runs the API container's entrypoint,
`node dist/db/migrate.js && node dist/index.js` - it takes the pre-migrate
snapshot, applies any pending migrations, and only then starts serving
traffic. Watch it happen:

```bash
docker compose logs -f api
```

Look for the migration count logged near the top of the output, then a
line indicating the server is listening. If a migration fails, the
container exits non-zero and never starts serving - Coolify in particular
will not route traffic to a half-migrated API, so your previous version
stays live in front of users while you investigate.

## 4. Verify [#4-verify]

```bash
curl -f https://your-domain.example.com/health
```

A `200` confirms the new process is up. Then open the app as an admin and
check the **About** page - the version shown there should match the tag
you just deployed. If it still shows the old version after the health
check passes, see [Troubleshooting](#troubleshooting) below.

{/* screenshot: the admin About page showing the running version number */}

## Rolling back [#rolling-back]

Point the image tag back at the previous version and redeploy, using the
same mechanism as step 2 (`.env.prod` + `docker compose up -d`, or the
Coolify `IMAGE_TAG` field).

```bash
IMAGE_TAG=<previous-version> docker compose --env-file .env.prod up -d api web
```

If a **migration** was the actual problem (not just a runtime bug), the
new schema may already be in place and simply starting the old image
against it can misbehave - restore the pre-migration snapshot first, then
start the old image:

```bash
docker compose --env-file .env.prod exec -T postgres \
  pg_restore -U "$SERVICE_USER_POSTGRES" -d "$POSTGRES_DB" --clean /backups/pre-migrate-<timestamp>.dump
```

Never run a newer database schema against an older application version -
roll the schema back with it if a migration is involved.

## Practices [#practices]

* Upgrade regularly - many small steps beat one giant leap; skipping many
  versions at once means more migrations run in one shot and more release
  notes to read before you understand what changed.
* Read the release notes for the versions you skip.
* On multi-container setups, upgrade `api`, web and `mcp` together - the
  images of one release belong together, and running mismatched versions
  across them is unsupported.

## Troubleshooting [#troubleshooting]

**The API container won't come back up after I bumped the version.**
Cause: a migration failed partway, or the new image needs an environment
variable an older version didn't require. Check `docker compose logs api`
for the actual error - a migration failure aborts before serving traffic,
so the previous version is never left half-migrated.
Fix: address the underlying error (missing variable, unreachable
database), or roll back to the previous image tag while you investigate.

**The health check passes but the admin About page still shows the old version.**
Cause: your browser is serving a cached copy of the web bundle.
Fix: hard-refresh the page. If it persists, confirm the `web` container
was actually rebuilt/pulled to the new tag too - a mismatched `web` vs
`api` tag from skipping the "upgrade them together" practice above also
produces this.

**I upgraded and now I need to go back.**
Cause: the new version introduced a regression for your setup.
Fix: follow [Rolling back](#rolling-back) above - point the image tag at
the previous version, restoring the pre-migration snapshot first if a
migration ran.


# AI assistant (/user-guide/ai-assistant)



If your workspace has AI turned on and you have permission to use it, orboto includes a built-in **AI assistant** - a chat panel that understands your workspace and can act in it for you. Open it with the **sparkle** icon in the top bar or press **Cmd/Ctrl + J**.

{/* screenshot: the AI assistant side panel open next to a project */}

> The assistant only appears when both the workspace feature is enabled and your account is allowed to use it. If you do not see the sparkle icon, it has not been enabled for you.

## What you can ask [#what-you-can-ask]

Talk to it in plain language. It can, for example:

* Answer questions about your tickets, projects, and docs ("what's overdue in the release?", "summarise this ticket").
* Find things ("show me high-priority bugs assigned to me").
* Draft and make changes for you (create a ticket, add a comment, update fields, add a [primer fact](/user-guide/knowledge/requirements-documents)) - always with your confirmation.
* **Take you to the right screen.** Ask it to open something ("open the analytics for this project") and it navigates there for you.

## How a conversation works [#how-a-conversation-works]

* Type your message and send it. The assistant streams its reply, and where it used your data it shows what it drew on.
* Start a **new chat** for a fresh topic (the old one stays reachable in your **history**), or **retry** the last answer to regenerate it in place.
* Select **branch** on any earlier turn to spin up a brand-new conversation that starts from that point - useful for exploring a different direction without losing the original thread.
* **Copy** any reply as plain text, or use **copy as Markdown** to paste it somewhere that renders formatting.

{/* screenshot: an assistant conversation with a reply and the new-chat / history / branch controls */}

### Temporary chats [#temporary-chats]

Before you send your first message in a new chat, you can flip it to a **temporary** (ghost) chat - it stays purely in memory and is never saved to your history. Once you've sent a message the choice locks in for that conversation; start a new chat to change it again.

## Giving it context [#giving-it-context]

* **Pin context** - type a ticket or doc key (for example `ACME-42` or `ACME-D7`) into the pin field to attach it, so the assistant answers about that item specifically. You can pin more than one.
* **Attach** a document or image (when supported by your model) so the assistant can read it as part of your question.

## Approvals: nothing happens without your yes [#approvals-nothing-happens-without-your-yes]

When the assistant wants to *change* something rather than just read, it pauses and shows an approval card before doing anything:

* A normal write (for example creating a ticket) needs a single **Approve**.
* A **destructive** action (for example deleting something) needs a clearer, separate confirmation - you have to type the exact ticket key to confirm before the button unlocks.

You can always **cancel** instead. This keeps you in control - the assistant proposes, you decide.

{/* screenshot: the assistant asking for approval before a destructive change, with the ticket-key confirmation field */}

## Model choice [#model-choice]

Where your workspace offers more than one AI model, a **model** selector (from the models your administrator has allow-listed) lets you pick which one answers this conversation, or leave it on the default.

## The AI features built into the product [#the-ai-features-built-into-the-product]

Beyond the chat panel, AI shows up throughout orboto (all optional, all gated on your workspace's settings):

* **On a ticket** - summarise, suggest a title, labels, or priority, estimate effort, split a big ticket, and ask questions about it. See [Projects and tickets](/user-guide/work/projects-and-tickets).
* **In search** - describe what you want in plain language. See [Search](/user-guide/knowledge/search).
* **In docs** - ask questions answered from your documentation. See [Docs and wiki](/user-guide/knowledge/docs-and-wiki).
* **Duplicate and related detection** - orboto flags likely duplicates and related tickets as you work.
* **Daily digest** - an optional AI-written summary of your day.
* **Retrospectives** - AI-assisted summaries of what happened in a milestone.
* **Requirements documents** - an AI-written executive summary and content translation, plus assistant-captured project facts. See [Requirements documents and reports](/user-guide/knowledge/requirements-documents).

## Troubleshooting [#troubleshooting]

* **The sparkle icon is missing.** AI needs to be enabled for the workspace AND for your account specifically - ask a workspace administrator.
* **An approval card won't let me confirm.** For a destructive action, the confirm field only unlocks once you type the exact ticket key shown on the card - a partial or mistyped key stays disabled.
* **I can't find an old conversation.** Check whether it was a temporary chat - those are never saved and can't be recovered once the panel closes.
* **The assistant's answer looks out of date.** Pin the specific ticket, project, or doc you're asking about so it reads current data rather than relying on general context.


# AI features (/user-guide/ai-features)



The [AI assistant](/user-guide/ai-assistant) is orboto's chat panel, but most of orboto's AI is not a chat at all - it is small, focused helpers built directly into the screens you already use. This page is the full reference for those: what each one does, exactly where to find it, and how to use it.

> Every capability on this page needs an AI provider configured for your workspace, and needs to be turned on. If none of this appears for you, ask your administrator to check **Admin → AI settings** (see [AI providers and models](/admin/ai/ai)). Some capabilities (semantic search, related tickets) additionally need **embeddings** configured - the same admin page shows whether that is on.

## Ticket summaries [#ticket-summaries]

**What it is.** A short, plain-language recap of a ticket - its description plus the discussion in its comments - so you can catch up without reading everything.

**Where it appears.** Open any ticket and use **Summarize** from the ticket's **AI actions** menu (the sparkle icon in the ticket header).

**How to use it.** Select it, wait a moment while orboto reads the ticket, and a summary appears in place. It is generated fresh each time you ask - nothing is stored automatically. The same summarizer works for docs and whole projects wherever a **Summarize** action appears.

Ticket summaries sit alongside the ticket's other AI actions (suggest a title, labels, priority, split into sub-tickets, and ask a question about the ticket) - see [AI actions on a ticket](/user-guide/work/tickets#ai-actions-on-a-ticket) for the full set.

{/* screenshot: a ticket with the AI actions menu open, Summarize highlighted */}

## Duplicate detection while creating a ticket [#duplicate-detection-while-creating-a-ticket]

**What it is.** As you type a new ticket, orboto quietly checks whether something very similar already exists, so you do not accidentally file the same bug or task twice.

**Where it appears.** The **new ticket** form, right above the title field, once your title is at least 8 characters long.

**How it works.** About half a second after you stop typing, orboto searches the project for close matches on your title and description. If it finds any, an amber banner appears:

* Up to three candidates are listed, each with its ticket key, current status, and a **similarity percentage**.
* A small **AI** badge on the banner means the match came from semantic understanding (comparing meaning, not just shared words) rather than plain keyword overlap - semantic matching needs embeddings configured on your workspace.
* Select a candidate to open it instead of creating a new ticket.
* Select the &#x2A;*×** to dismiss the banner for this attempt - it reappears if you materially change the title again.

This warning is advisory: dismissing it and creating the ticket anyway is always allowed for a normal user. Some workspaces additionally configure a **hard block** that refuses the create outright above a very high similarity score - if you hit that, see Troubleshooting below.

{/* screenshot: the new-ticket form with the amber "looks similar to 2 existing tickets" banner and its candidate list */}

### Overlapping content inside an existing ticket [#overlapping-content-inside-an-existing-ticket]

A related, second check runs on a ticket you already have open: if a paragraph in its description closely matches a paragraph in another ticket's description, a banner reports how many tickets and paragraph matches were found. Expand **Show details** to see each matching paragraph side by side with its source, or dismiss the banner if the overlap is intentional (for example, a checklist template repeated on purpose).

## Related-ticket suggestions [#related-ticket-suggestions]

**What it is.** A live list of other tickets in the same project that are about a similar topic to the one you are looking at - useful for finding prior work, a root cause, or something you should link before you start.

**Where it appears.** A **Related tickets** panel in the ticket detail view, below the main fields.

**How to use it.** The panel lists up to five related tickets with their status and a similarity percentage, most-similar first. Tick **include closed** to also see closed tickets (useful for "has this been solved before?"). Select any entry to open it. If your workspace has no embeddings configured yet, this panel does not appear - it needs semantic matching to work, not just keyword overlap.

{/* screenshot: the ticket detail panel with the Related tickets list open, similarity percentages visible */}

## Effort estimation [#effort-estimation]

**What it is.** A suggested time estimate for a ticket, based on how long genuinely similar tickets took to close in the past - not a guess, a comparison.

**Where it appears.** The **Suggest estimate** button in the ticket detail panel's sidebar.

**How to use it.**

1. Select **Suggest estimate**.
2. Pick which population of past tickets to compare against: **human**-completed, **bot**-completed, or **mixed**. Bots and humans often work at very different speeds, so mixing them can skew the number - pick the pool that matches who will actually do this ticket.
3. orboto returns an estimate in hours, a plausible **range**, a short rationale, and how many historical tickets it drew on.
4. Select **Apply** to write the suggested value into the ticket's estimate field, or dismiss it and set your own.

If very few comparable tickets exist yet, the estimate is based on a small sample - the "based on N tickets" line tells you exactly how much evidence backed the number, so you can judge how much to trust it.

{/* screenshot: the AI effort estimate panel showing the estimate, range, rationale, and Apply button */}

## Natural-language search [#natural-language-search]

Search also has an AI mode: describe what you want in plain words (for example "high priority bugs assigned to me that are overdue") instead of clicking through filters, and orboto turns it into the right query. This is covered in full, including how the detected filters and fallback behaviour work, on the [Search](/user-guide/knowledge/search#ai-search-natural-language) page.

## Retrospective generation [#retrospective-generation]

**What it is.** An AI-written retrospective document for a milestone you just closed: what shipped, what took longer than planned, and any risk signals that fired along the way - with every claim traceable back to a real ticket.

**Where it appears.** Open a milestone's group actions and select **Generate retro**.

**How to use it.**

1. Select **Generate retro** on a milestone.
2. orboto gathers the milestone's tickets, logged time, and any alerts that fired during it, and asks the model to write a structured summary in four sections. Every ticket the retro refers to is cited inline with its ticket key, so you can verify any claim against the real ticket.
3. Review the result. **Copy markdown** to paste it elsewhere, or save it directly as a page in a documentation space so the retrospective becomes part of your project's history.

{/* screenshot: the retrospective dialog with the generated markdown and a Save as doc option */}

## The daily digest [#the-daily-digest]

**What it is.** An optional once-a-day email that summarises what changed on the tickets you care about - assignments, status moves, and new comments - written up by AI instead of listing raw events.

**Where you turn it on.** Your [profile](/user-guide/everyday/account-and-security) has a **Daily digest email** checkbox, off by default. Once on, you get a short email most mornings (around 07:00 UTC) covering the last 24 hours of activity on tickets you are assigned to or created - nothing from projects you are not part of.

If nothing relevant happened in that window, no email is sent that day - the digest never arrives empty just to remind you it exists. The digest is one of several notification delivery options; see [Notifications](/user-guide/everyday/notifications#the-daily-digest) for how it fits alongside the notification bell, per-event email, and chat channels. An administrator can customise its subject and wording from the email template editor if your workspace wants a different tone.

## Content translation for readers [#content-translation-for-readers]

orboto can translate content on the spot so people reading in a different language get something they can actually understand, in two places:

**While writing.** Select any text inside a ticket description, a comment, or a doc page and a small floating toolbar appears. Choose **Translate**, then pick a target language from the list (English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Swedish, Japanese, Chinese, Korean, Russian, Turkish). orboto shows your original text and the translation side by side - **Accept** to replace the selection with the translated version, or discard it and keep your original wording. The same floating toolbar also offers **Improve**, **Shorten**, **Lengthen**, and **Fix grammar**, if you want AI help with wording rather than language.

{/* screenshot: text selected in the editor with the floating AI toolbar and the Translate language picker open */}

**Keeping a workspace's language consistent.** If your workspace expects tickets in one language and you (or someone else) writes one in a different language, an advisory notice appears on that ticket naming the language it detected and the language expected. Where you have permission to edit the ticket, a one-click **Translate** action on that notice rewrites the title and description into the expected language for you - useful for keeping a shared project readable for the whole team, not just for you.

Generated documents have their own, separate translation option - see [Requirements documents and reports](/user-guide/knowledge/requirements-documents#options-that-shape-the-document) for translating a whole generated report into another language.

## Troubleshooting [#troubleshooting]

* **I don't see any AI actions anywhere.** AI needs to be configured and enabled for your workspace - ask an administrator to check Admin → AI settings. If AI is on generally but one specific feature (related tickets, semantic duplicate matching) is missing, that feature specifically needs embeddings, which is a separate toggle from chat.
* **Creating a ticket was refused with a duplicate error instead of just warned.** Your workspace has the stricter duplicate guardrail turned on, which refuses a create above a very high similarity score instead of only warning. Change the title or description so it is clearly distinct from the existing ticket, or open and update the existing one instead.
* **The Related tickets panel never shows anything.** It needs embeddings configured on your workspace, and it needs the ticket itself to have been processed into an embedding yet - a ticket created moments ago may not have one until the background worker catches up.
* **My daily digest never arrives.** Confirm the checkbox is on in your profile, and remember it only sends when there was actual activity on your tickets in the last 24 hours - a quiet day means no email.
* **The estimate looks way off.** Check which audience pool you compared against (human vs bot vs mixed) and how many tickets it was based on - a low count or the wrong pool both produce a less reliable number.


# Budget and cost tracking (/user-guide/analytics-budget)



This page covers the money-related cards on a project's
[Analytics](/user-guide/analytics) page: **Budget** and **Loaded member
cost*&#x2A;. Both need the &#x2A;*`budget:view`** permission - without it, they simply
don't appear on the page, and the Actual cost overview tile is hidden too.

## Setting a budget and rates first [#setting-a-budget-and-rates-first]

Nothing on this page shows a meaningful number until a budget and at least
one hourly rate exist somewhere in the project. There are three places to
configure this:

1. **Project settings -> Budget tab** - set **Budget hours** and/or
   **Budget amount** (with a **Currency**) for the whole project, plus a
   **Project hourly rate** used when a contributor has no rate of their own.
   Either budget field can be left empty; a project can track hours only,
   money only, both, or neither.
2. **Milestone budgets** - each milestone can carry its own Budget hours /
   Budget amount, edited inline in the **Milestone budgets** table at the
   bottom of the Budget card (needs `milestone:edit`) or from the milestone's
   own settings. A milestone without its own budget falls back to the
   project's.
3. **Per-person hourly rate** - set on a user's account under
   **Admin -> Users**, alongside an optional **Overhead factor** (a
   loaded-cost multiplier on top of the rate, e.g. `1.3` for +30% to cover
   employer costs beyond the raw wage - leave it empty to inherit the
   workspace default).

{/* screenshot: project settings Budget tab with budget hours, budget amount, currency and hourly rate fields */}

### How a rate is resolved [#how-a-rate-is-resolved]

Whenever orboto needs to price someone's logged time, it resolves a rate
through a cascade, stopping at the first one that's set:

1. That **person's own hourly rate** (Admin -> Users).
2. The **project's hourly rate** (Project settings -> Budget).
3. The **customer's default hourly rate** (set on the customer record this
   project belongs to, if any).
4. If none of those are set, the rate is &#x2A;*"none"** - the person's cost
   shows as 0, but they're still listed with a visible "no rate" marker
   rather than silently vanishing from the table.

This cascade is **live, not historical**: cost is always computed from
whoever's rate is configured *right now*, at query time - a time entry does
not remember what the rate was on the day it was logged. Raising someone's
rate today changes the reported cost of every hour they've ever logged on
this project, immediately.

## Budget card [#budget-card]

{/* screenshot: the budget card with the time and cost meters, per-user cost table, and milestone budget table */}

If no budget is configured, the card just prompts you to set one - it never
substitutes the ticket estimate total as a stand-in budget.

* **Time budget** / **Cost budget** meters - used hours or spend against
  the configured budget, as a percentage bar. Turns red past 100%.
* **Projected** (under each meter) - not the same thing as "used." It is a
  forward-looking estimate: the sum of every ticket's **time estimate**
  (not logged time), priced by the rate cascade above - split evenly across
  a ticket's Responsible assignees when it has any, or the project/customer
  rate for unassigned work. Read "Projected: over budget" as "if the
  remaining estimated work costs what the plan says, the total will exceed
  the budget" - a warning based on plan, not a report of what already
  happened.
* **Per-user actual cost table** - each contributor's logged hours, their
  resolved hourly rate, and their cost, so you can see cost per person, not
  just the total.
* **Milestone budgets** table - the same used/budget comparison per
  milestone, with an inline edit control if you hold `milestone:edit`. A
  warning banner appears when milestone budgets **together** exceed the
  project's overall budget ("Milestones over-allocate the project budget") -
  useful for catching a plan that adds up wrong before it becomes a problem.

## Loaded member cost [#loaded-member-cost]

{/* screenshot: the loaded member cost card with labor cost, AI cost, loaded cost and the per-member table */}

Goes beyond the raw hourly rate to the **fully loaded cost** of a person's
(or agent's) time on this project, scoped by the date-range picker:

* **Loaded rate** = base hourly rate (same cascade as above) x the
  **overhead factor**. A rate shown as `50 EUR/h (x1.3)` means 65 EUR/h is
  actually charged in the totals.
* **Labor cost** = loaded rate x hours logged in the range.
* **AI cost** = AI spend attributable to that person: their own AI usage
  plus the usage of any agent accounts they own, split into **orboto AI**
  (priced usage of orboto's own AI features) and **External** (spend from
  external tools like Claude Code or Codex, entered separately). AI cost is
  **workspace-scoped, not project-scoped** - it reflects that person's total
  AI spend across every project they touch, not just this one, because AI
  usage itself carries no per-project dimension.
* **Loaded cost** = Labor cost + AI cost.
* **Incl. agents** ("true cost") = Loaded cost, plus the loaded cost of any
  agent accounts that person operates - so a human who runs several AI
  agents sees their real total footprint, not just their own hours.

An **External AI by provider** breakdown, when present, shows external
spend split by provider (e.g. "Claude Code", "Codex"). A footnote clarifies
that converted foreign-currency external spend uses the amount entered at
the time, not a live exchange rate.

## How this connects to customer reports [#how-this-connects-to-customer-reports]

The **Customer report** builder (opened from the project header, not from
Analytics) has a **money** pricing mode that prices work at the project's or
customer's rate for an external audience - deliberately excluding your
internal per-person rate and overhead, since a customer should never see
your internal cost structure. See
[Requirements documents](/user-guide/knowledge/requirements-documents)
for that feature; it needs `budget:view` for money pricing, the same
permission as this page.

## Troubleshooting [#troubleshooting]

* **The Budget card just says "No budget configured for this project."**
  Set **Budget hours** and/or **Budget amount** in Project settings -> Budget
  * see [Setting a budget and rates first](#setting-a-budget-and-rates-first)
    above.
* **A person shows "no rate" instead of a cost.** None of the three rate
  levels (their own, the project's, the customer's) are set for them. Set at
  least the project's hourly rate as a fallback that covers everyone.
* **Costs changed after I didn't log any new time.** Someone's hourly rate
  or overhead factor was changed. Cost is always computed from the
  currently configured rate, not a historical snapshot - see
  [How a rate is resolved](#how-a-rate-is-resolved) above.
* **"Milestones over-allocate the project budget."** The sum of every
  milestone's own budget exceeds the project-level budget. This is a
  planning warning, not an error - either raise the project budget or trim
  a milestone's allocation.
* **AI cost looks too high / includes work from other projects.** Expected
  * AI cost is attributed per person across the whole workspace, not per
    project, because AI usage itself has no project dimension.
* **The Loaded member cost card is empty.** No time was logged by anyone in
  the selected date range - widen the range picker.


# Earned Value Management (/user-guide/analytics-earned-value)



The **Earned Value** panel sits near the bottom of a project's
[Analytics](/user-guide/analytics) page, grouped with the
[Budget card](/user-guide/analytics-budget). If you've never used
Earned Value Management (EVM) before, this page teaches the whole concept
from scratch - what each number means, how orboto computes it from your
tickets and time entries, and how to read a healthy picture from an
unhealthy one.

{/* screenshot: the Earned Value panel with the PV/EV/AC chart and the SPI/CPI/EAC/VAC tiles */}

## The idea, in one sentence [#the-idea-in-one-sentence]

EVM answers one question a plain burndown chart can't: &#x2A;*"for the money and
time we've spent so far, did we get the progress we should have?"** A
project can look fine on a burndown (tickets are closing) while quietly
running over budget, or look fine on budget (spend is on track) while
quietly falling behind schedule. EVM catches both at once by comparing three
numbers.

## A worked example [#a-worked-example]

Imagine milestone **Sprint 7** in project **ACME**, budgeted at **100
hours** (its `BAC`, explained below), running Monday through the Friday of
the following week - **10 working days**. It contains 10 tickets, each
estimated at 10 hours (100 hours of estimated work in total, matching the
budget).

Today is the **5th working day** - exactly the halfway point. So far:

* **4 tickets have been closed** (40 hours of estimated work delivered).
* The team has **logged 44 hours** of actual time.

Here is what EVM reports, and what each figure means.

### The three curves [#the-three-curves]

| Curve                  | What it is                                                                                                         | In this example                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| **Planned Value (PV)** | What you *planned* to have earned by now, if work landed exactly on schedule.                                      | Day 5 of 10 = halfway -> `100h x 5/10 = 50h`                       |
| **Earned Value (EV)**  | What you've *actually* earned - the budgeted value of the work that's genuinely done, not the time spent doing it. | 40h of the 100h estimated work has closed -> `100h x 40/100 = 40h` |
| **Actual Cost (AC)**   | What it has *actually cost* so far.                                                                                | 44 hours were logged -> `AC = 44h`                                 |

Notice EV is **not** "how many hours got logged" and it is **not** "40% of
the way through the checklist" either - it is specifically the **budget
share of the work that's actually closed**, weighted by each ticket's
estimate. A ticket that's 90% done but still open contributes nothing under
orboto's default crediting rule (more on that below).

### Reading the gap: SPI and CPI [#reading-the-gap-spi-and-cpi]

Two ratios turn those three numbers into a straight "ahead or behind" read:

* **Schedule Performance Index (SPI) = EV / PV** -> `40 / 50 = 0.8`.
  SPI of **1.0 is exactly on schedule**. **Above 1** means ahead. **Below
  1** means behind, and by how much: an SPI of 0.8 means the team is
  earning value at **80% of the planned pace** - for every 5 hours of
  schedule that passed, only 4 hours of value came out the other end.
* **Cost Performance Index (CPI) = EV / AC** -> `40 / 44 ≈ 0.91`.
  CPI of **1.0 is exactly on budget**. **Above 1** means you're getting more
  value than you're paying for (under budget). **Below 1** means the
  reverse: a CPI of 0.91 means every hour spent is buying about **0.91
  hours of earned value** - if that efficiency holds for the rest of the
  work, the milestone will end up costing roughly `1 / 0.91 ≈ 10%` more
  than planned.

In this example: **SPI 0.8 and CPI 0.91** together describe a milestone
that is both a bit behind schedule and running a bit over budget - the
classic pattern EVM exists to catch early, while there's still runway to
react.

### Forecasting the ending: EAC and variance [#forecasting-the-ending-eac-and-variance]

* **Estimate at Completion (EAC) = BAC / CPI** -> `100 / 0.91 ≈ 110h`.
  If the current cost-efficiency holds for the rest of the work, this is
  the projected **final cost**.
* **Estimate to Complete (ETC) = EAC - AC** -> `110 - 44 = 66h`. How much
  more spend is expected before the milestone is done.
* **Variance at Completion (VAC) = BAC - EAC** -> `100 - 110 = -10h`. A
  **negative** VAC is a projected overrun (spending more than budgeted); a
  **positive** VAC is a projected underrun.
* **To-Complete Performance Index (TCPI) = (BAC - EV) / (BAC - AC)** ->
  `(100 - 40) / (100 - 44) = 60 / 56 ≈ 1.07`. This is the efficiency the
  **remaining** work needs to hit to still land on the *original* budget.
  A TCPI above 1 means the team needs to get **more** efficient than it's
  been so far to recover - not just keep going. A TCPI far above 1 (say,
  well past 1.1-1.2) is usually a sign that the original budget itself
  needs revisiting rather than squeezed harder.

## The tiles and chart on the page [#the-tiles-and-chart-on-the-page]

The panel shows **SPI, CPI, SV (schedule variance, EV - PV), CV (cost
variance, EV - AC), EAC and VAC** as tiles, colour-coded green when the
number is on the healthy side (SPI/CPI at or above 1, SV/CV/VAC at or above
0\) and red otherwise, plus a line chart of the PV / EV / AC curves across
the milestone's window. PV is drawn all the way to the milestone's end date
as the baseline reference; EV and AC only accrue up to **today** - they are
never projected into the future, only PV is.

## Controls [#controls]

* **Hours / Money** toggle - switches the whole panel's unit. Money needs
  `budget:view`; without it, only Hours is offered.
* **0-100 / 50-50** toggle (labelled with a hint on hover) - how an
  in-progress ticket earns credit before it closes:

  * **0-100** (default): a ticket earns nothing until it closes, then all
    of its estimate-weighted share at once.
  * **50-50**: a ticket earns **half** its share the moment work first
    starts on it, and the other half on close.

  Important nuance: "started" here means **the first time entry was logged
  on the ticket** - not the moment its status moved to "In Progress." A
  ticket sitting in an in-progress column with zero logged time has not
  "started" under this rule yet.
* **Milestone scope** - there is no separate milestone picker on this
  panel; it follows the **same dropdown that lives inside the Burndown
  card** further up the page. Leaving it on "All milestones" scopes EVM to
  the whole project instead of one milestone (see below).

## Exactly what orboto feeds into the calculation [#exactly-what-orboto-feeds-into-the-calculation]

* **BAC (Budget at Completion)** = the selected milestone's budget (hours
  or money), **falling back to the project's budget** if the milestone has
  none set.
* **The window** = the milestone's start and end dates. With no milestone
  selected (project scope), the window is the **span across every
  milestone in the project** - the earliest milestone start to the latest
  milestone end - not the project's own creation date.
* **PV ramps over working days**, not raw calendar days: weekends,
  public holidays, and company closures (the same blocked-days calendar
  used by [Time tracking](/user-guide/planning/time-tracking) and
  [Capacity](/user-guide/planning/capacity)) are skipped, so a
  five-day sprint with one holiday in it ramps PV over four working days,
  not five calendar ones.
* **EV** = `BAC x (sum of estimates of tickets counted as earned) / (sum of
  estimates of every ticket in scope)`. **Tickets with no estimate
  contribute zero weight either way** - they don't inflate the total and
  they can never earn anything themselves. If **every** ticket in scope is
  unestimated, there is nothing to divide by and EV stays 0 regardless of
  how many tickets close.
* **AC (hours mode)** = the sum of logged time entries up to today.
  &#x2A;*AC (money mode)** = those same hours priced per contributor: their own
  hourly rate if set, otherwise the **project's** hourly rate. Unlike the
  [Budget card](/user-guide/analytics-budget#how-a-rate-is-resolved),
  EVM's money mode does **not** fall back further to the customer's default
  rate - a contributor with neither a personal nor a project rate
  contributes 0 cost here even if the Budget card would have priced them
  via the customer.
* **As-of date** is always **today** in the UI. The underlying API accepts
  a historical `asOf` date for scripted/agent use, but the panel itself has
  no date picker for it.
* Only tickets you're allowed to see count - the same private-ticket and
  guest-visibility rules as the rest of the project apply.

## Reading a healthy vs unhealthy picture [#reading-a-healthy-vs-unhealthy-picture]

* **Healthy**: the EV line tracks close to the PV line (on schedule), and
  the AC line sits at or below EV (on or under budget). SPI and CPI both
  sit at or above 1.
* **Behind schedule, on budget**: EV visibly below PV, but AC also below or
  near EV. SPI under 1, CPI near or above 1 - slow, but not burning cash to
  compensate.
* **On schedule, over budget**: EV tracks PV, but AC rides well above EV.
  SPI near 1, CPI under 1 - hitting dates by spending more than planned to
  get there.
* **Both behind and over budget** (the worked example above): EV lags PV
  *and* AC rides above EV. This is the pattern worth raising early - it
  rarely self-corrects without a scope, schedule, or budget change.
* **Common misreading**: EV is not "percent of tickets touched" or "percent
  of time spent." A ticket that's 90% finished but still open earns 0% under
  the default 0-100 rule (or 50% under 50-50, once time was first logged on
  it) - never a smooth 90%. orboto does not offer a %-complete credit rule
  today; if your team routinely under-reports progress because of this,
  switching to 50-50 gives partial credit earlier without needing one.

## Requirements & empty states [#requirements--empty-states]

EVM needs a baseline before it can compute anything, so the panel tells you
exactly what's missing rather than showing a blank chart with no
explanation:

* **"Set start and end dates on the milestone..."** - the milestone (or, in
  project scope, its milestones collectively) has no start/end window. Fix:
  set the milestone's start and end date in its details.
* **"Set a budget on this milestone (or the project)..."** - neither the
  milestone nor the project has a budget configured in hours or money. Fix:
  set one in [Project settings, or the milestone's own budget field](/user-guide/analytics-budget#setting-a-budget-and-rates-first).

## Troubleshooting [#troubleshooting]

* **The panel shows an empty state instead of a chart.** Read the message -
  it's always one of the two requirements above, never a generic failure.
* **EV never moves even though tickets are closing.** Check whether the
  closing tickets actually have **estimates** set. An unestimated ticket
  earns nothing when it closes, and if the whole scope is unestimated, EV
  is permanently 0. Add estimates and it will start moving.
* **Money mode is missing (only Hours is offered).** You don't have
  `budget:view` on this project. Ask a project admin.
* **AC in money mode looks lower than I expected.** EVM's money mode only
  falls back from a contributor's own rate to the **project** rate, not the
  customer's default rate - see
  [Exactly what orboto feeds into the calculation](#exactly-what-orboto-feeds-into-the-calculation)
  above. Set a project hourly rate as a safety net if you rely on the
  customer-level fallback elsewhere.
* **SPI or CPI shows a dash instead of a number.** They're undefined when
  the denominator is exactly 0 - SPI needs PV greater than 0 (normal right
  at the very start of a milestone, before any working days have elapsed)
  and CPI needs AC greater than 0 (before any time has been logged yet).
  This resolves itself once the milestone is underway.
* **Switching between 0-100 and 50-50 changes EV a lot.** Expected - 50-50
  gives partial credit for started-but-not-closed work, so it reports a
  higher EV (and usually a healthier SPI) than 0-100 for the same actual
  progress. Pick whichever credit rule matches how your team actually
  wants "in progress" work represented, and stay consistent with it over
  time so comparisons across periods stay meaningful.


# Flow, cycle time and forecasting (/user-guide/analytics-flow)



This page covers the cards on the [Analytics](/user-guide/analytics)
page that describe how work *flows* through your project's statuses: cycle
time, lead time, delivery forecasting, work-in-progress, and bottlenecks.
Open a project's Analytics page and scroll past Workload to find them.

None of the cards on this page are scoped by the top-of-page date-range
picker. Each uses its own fixed lookback window, noted per card below - that
is a deliberate difference from Overview, Velocity, Cycle time, Workload,
Loaded member cost and Collaboration, which the range picker does affect
(see the scoping table on the main [Analytics](/user-guide/analytics)
page).

## Cycle time (legacy) [#cycle-time-legacy]

{/* screenshot: the cycle-time card with average, median and the histogram */}

The **average** and **median** number of days from a ticket's creation to
its close, plus a histogram of how many tickets fell into each duration
bucket (0-1 day, 1-3, 3-7, 7-14, 14-30, 30+ days). `WONT_FIX` tickets are
excluded - their "duration" measures how long until someone gave up, not how
long until something shipped.

Unlike the other cards on this page, **this one is scoped by the
date-range picker** on the main Analytics page - it only counts tickets
closed inside the selected range. That is why this card's average can
disagree with the median lead/cycle time shown in Flow & lead time below,
which always looks at the project's whole history.

**How to read it:** prefer the median over the average - a handful of very
old or very slow tickets can drag the average up while most work actually
finishes quickly. A wide, flat histogram (tickets spread across every
bucket) means delivery time is unpredictable; a histogram bunched in one or
two buckets means it's consistent.

## Flow & lead time [#flow--lead-time]

{/* screenshot: the flow & lead time table, grouped by overall / work origin / size / type */}

Three different timings, shown side by side so they're never confused with
each other:

* **Lead time** - created to done. Includes time spent waiting in a queue
  before anyone touched it.
* **Cycle time** - first moved to "in progress" to done. Excludes the queue
  wait; measures active handling only.
* **Effort** - actual tracked time logged on the ticket (hours), not a
  calendar span at all.

Each is shown as &#x2A;*median (p90)** - the typical value, with the 90th
percentile in parentheses so you can see the long tail without it being
hidden by an average. Rows split the same tickets by **group** (overall, and
by who did the work: agent / human / mixed), by **size** (an estimate-size
bucket: none, XS, S, M, L, XL) and by **type** (ticket type). A cell that
reads "-" means that group has no sample.

This card always looks at the project's **entire history** (not the
date-range picker) and, by default, excludes "degenerate one-shot" tickets -
ones created and closed essentially instantly with zero tracked effort,
which are almost always a backfill or an import artifact rather than real
work, and would otherwise pull cycle time toward zero. The excluded count is
shown so the sample size stays honest. Tickets that reached done but never
had any of the timeline data this card needs are also counted separately as
**untracked**, not silently dropped.

## Delivery forecast [#delivery-forecast]

{/* screenshot: the delivery forecast card with the p50/p85/p95 completion bands */}

Answers "when will the remaining work realistically be done?" - not with one
false-precise date, but with a **Monte-Carlo simulation**: orboto looks at
how many tickets your team actually closed per week over roughly the last 12
weeks, then simulates finishing the remaining tickets thousands of times by
repeatedly drawing a random week's throughput from that history. The result
is a distribution of "how many weeks did it take" across all those
simulated runs.

Three bands are reported:

* **p50** - the median simulated run. Half of the simulations finished by
  this date. Read this as "the most likely date", not a safe commitment.
* **p85** - 85% of simulated runs finished by this date. A more conservative
  number to actually promise a stakeholder.
* **p95** - 95% of simulated runs finished by this date. The number to use
  when being late is expensive.

**Remaining work** defaults to the open tickets in the currently selected
milestone (from the Burndown card's milestone dropdown), or the whole
project's open backlog when no milestone is selected.

**Why throughput, not cycle time:** "how long until N tickets are done" is a
question about *flow rate*, not about any single ticket's calendar duration.
A Monte-Carlo simulation over historical throughput captures the week-to-week
variance that a single "average cycle time × ticket count" estimate would
hide.

If there isn't enough history yet - fewer than 3 tickets completed in the
lookback window - the card tells you so directly instead of guessing:
"Not enough completed-work history to forecast yet."

## Flow metrics [#flow-metrics]

{/* screenshot: the flow metrics stat tiles, cumulative flow diagram, and throughput chart */}

A Kanban-style read on the last 30 days:

* **Current WIP** - leaf tickets (not epics) currently in progress or in
  review. This is "how much is actually being worked on right now."
* **Epic WIP** - epics currently in progress or in review, counted
  separately so a long-running phase epic doesn't inflate the leaf-work
  number above.
* **Flow efficiency** - across completed tickets, the median share of a
  ticket's total lead time that was spent actively being worked (in progress
  or in review) versus just waiting. A ticket with 20% flow efficiency spent
  four-fifths of its life sitting in a queue.
* **Throughput** - tickets completed in the window (also charted per week
  below).
* **Aging WIP** - the count of currently open tickets tracked in the aging
  table further down.

Below the tiles:

* **Cumulative flow diagram (CFD)** - a stacked area chart, one band per
  status category (To Do / In Progress / In Review / Done), showing how many
  tickets sat in each on each day. **Widening bands reveal bottlenecks**: if
  the In Review band keeps getting thicker while In Progress stays thin,
  review is where work is piling up, not development.
* **Throughput per week** - the same completed-per-week count as the CFD's
  Done growth, as a bar chart.
* **Aging work in progress** - open tickets ranked by how long they've sat
  in their *current* status, with their total age alongside. Use this to
  find tickets that have quietly stalled.

Degenerate one-shot tickets (see Flow & lead time above) are excluded from
throughput and flow efficiency here too, with the excluded count shown.

## Bottleneck & predictability [#bottleneck--predictability]

{/* screenshot: the bottleneck card with dwell times, predictability ratings, and worst-aging tickets */}

Looks at the last 90 days:

* **Bottleneck (slowest status)** - the status category with the longest
  **median dwell time** across completed tickets - literally, where work
  spends the most time sitting before moving on.
* **Median time in status**, per category, with a trend arrow: an upward red
  arrow means dwell in that status has gotten worse recently versus earlier
  in the window (more than 15% slower); a downward green arrow means it's
  improved; a flat dash means no meaningful change.
* **Delivery predictability** - how *consistent* completed tickets' cycle
  time is, per cohort (agent-only / human-only / mixed / combined), using
  the **coefficient of variation** (standard deviation divided by the mean).
  A low coefficient means most tickets take a similar amount of time; a high
  one means duration is all over the place even if the average looks fine.
  Ratings: **High** (coefficient under 0.5) - trustworthy, plan around it
  confidently. **Medium** (under 1.0) - usable, but pad your estimates.
  **Low** (1.0 or above) - risky; don't promise a date off this cohort's
  average. **Insufficient** - fewer than 3 completed tickets in the cohort,
  too little signal to rate at all.
* **Worst-aging open tickets** - the open tickets that have sat longest in
  their current status, with their assignee, so you know who to check in
  with.

Predictability pairs with [Estimation accuracy](/user-guide/analytics-team#estimation-accuracy):
accuracy tells you *how far off* your estimates tend to run; predictability
tells you *how consistent* that gap is.

## Troubleshooting [#troubleshooting]

* **"No flow data yet" / "No completed tickets with usable timing yet."**
  These cards need completed tickets with real status-transition history.
  A brand-new project, or one whose tickets were all imported already-closed
  without transition timestamps, won't have anything to show yet.
* **Sample sizes look smaller than the ticket count I'd expect.** Degenerate
  one-shot tickets (instant create-to-close, zero tracked effort) are
  excluded from cycle time distributions - the excluded count is shown next
  to the table so you can see how many were dropped and why.
  Untracked tickets (missing timeline data entirely) are counted separately,
  not silently folded into the sample.
  This exclusion behaves the same way for the whole page (Flow & lead time,
  Flow metrics, Bottleneck): the same denominator logic runs everywhere.
* **The forecast says "insufficient" / won't show dates.** Fewer than 3
  tickets completed inside the lookback window (about the last 12 weeks by
  default). Wait for more throughput history, or extend the window via the
  API/agent tools if you need a longer look-back.
* **Cycle time (legacy card) and Flow & lead time disagree.** Expected - the
  legacy Cycle time card is scoped by the date-range picker and reports a
  mean; Flow & lead time always looks at full project history and reports a
  median. They are answering related but different questions.


# Estimation, collaboration and activity (/user-guide/analytics-team)



This page covers three more cards on the project's [Analytics](/user-guide/analytics)
page - Estimation accuracy, Human + agent collaboration, and Git activity -
plus the Summarize project button. Scroll to the bottom half of the page to
find them.

## Estimation accuracy [#estimation-accuracy]

{/* screenshot: the estimation accuracy table with multiplier, median ratio and confidence per cohort */}

Scores how your estimates compare to what actually happened, across every
completed ticket in the project's history (not scoped by the date-range
picker), and turns that into a **correction multiplier** you can apply to
future estimates.

**Worked example:** say your team estimated a ticket at 5 hours, and it
actually took 7 hours. That ticket's ratio is 7 / 5 = 1.4. Across many
tickets, orboto takes the **median** ratio (robust to one wildly-off ticket
skewing an average) and calls it the cohort's **multiplier**. A multiplier
of 1.4x means: when you estimate a new ticket at 5 hours, plan for roughly
5 × 1.4 = 7 hours in practice.

* **Multiplier above 1** - work tends to run longer than estimated (the
  common case). **Below 1** - estimates tend to run high (padding baked in).
  **Around 1** - estimates are well calibrated already.
* Rows split by **cohort**: agent-only, human-only, mixed, and combined (all
  completed tickets together) - so you can see whether agents and humans
  have different estimation blind spots.
* **Confidence** reflects sample size, not accuracy: **Insufficient** (no
  usable samples), **Low** (1-4), **Medium** (5-14), **High** (15 or more).
  A high multiplier shown with low confidence is a hint, not a rule to
  apply yet.

**Where the "actual" side of the ratio comes from** - orboto prefers the
most trustworthy signal available per ticket and falls back gracefully, so
older tickets with less tracked data still contribute something rather than
being dropped: tracked effort (logged time) first, then cycle time (first
"in progress" to done) if nothing was logged, then lead time (created to
done) as a last resort. Tickets with no usable signal at all - closed with
zero logged time, no status-transition history, and effectively instant -
count separately as "untracked" rather than distorting the ratio.

## Human + agent collaboration [#human--agent-collaboration]

{/* screenshot: the collaboration card with human-only/mixed/agent-only counts and the effort trend */}

Classifies every ticket that had activity (a time entry, a comment, or a
tracked status change) as **human-only**, **agent-only**, or **mixed**,
based on who actually did the work - not who is assigned. A ticket driven
entirely by an AI agent's comments and commits, with a human only assigned
to it on paper, still counts as agent-only here.

* **Agent share of effort** - agent-logged minutes divided by all logged
  minutes, shown as a percentage, both as a headline figure and as a
  week-by-week trend line so you can see whether agent involvement is
  growing.
* **Per-member table** - each person's (or bot account's) total logged
  hours and their own agent-share percentage.
* **Tickets by collaboration type** - a drill-down list of the most
  recent agent-involved tickets with their classification badge.

This card is scoped by **both** the date-range picker and the milestone
selector inside the Burndown card above - a milestone picked there narrows
this card to that milestone's tickets too.

## Git activity [#git-activity]

{/* screenshot: the git activity feed with commit and pull-request entries and the filter chips */}

A combined, filterable feed of commits and pull requests linked to this
project through a connected git integration, at the very bottom of the
Analytics page. Filter chips switch between All / Commits / PRs, and the PR
chip shows an open/merged/closed breakdown. "Load more" fetches further
back in batches of 20. The card is hidden entirely if the project has no
git activity at all under the "All" filter - there's nothing to show yet
rather than an empty box.

This requires a connected repository; setting that up is a separate topic
from analytics.

## Summarize project (AI) [#summarize-project-ai]

{/* screenshot: the Summarize project button open, showing the generated paragraph */}

The sparkle-icon **Summarize project** button in the page header (only
visible when your workspace has AI configured) asks the assistant to write
a short, current-state paragraph about the project on demand - a quick
narrative complement to the charts, not a replacement for them. See
[AI assistant](/user-guide/ai-assistant) for what it draws on.

## Troubleshooting [#troubleshooting]

* **Estimation accuracy shows "-" or "Insufficient" everywhere.** The
  project doesn't have enough completed tickets with a usable actual-versus-
  estimate signal yet. This needs completed tickets that were also
  estimated - an unestimated ticket contributes nothing to its ratio.
* **"No human or agent activity in this range yet."** Either nothing has
  happened in the selected date range, or (if you narrowed by milestone)
  that milestone has no activity. Widen the range or clear the milestone
  filter.
* **The collaboration numbers look different after switching milestones.**
  Expected - the milestone selector on the Burndown card also scopes this
  card, even though it isn't visually next to it. See the scoping note on
  the main [Analytics](/user-guide/analytics) page.
* **Git activity panel is missing entirely.** Either the project has no
  connected git repository, or it has one but there's genuinely no commit
  or PR history recorded yet.


# Analytics (/user-guide/analytics)



Every project has an **Analytics** page: a dashboard built entirely from
tickets you already have - their statuses, dates, estimates, and logged time.
You do not configure anything to see the basic charts; money-related figures
need a budget and a permission (see below).

## Where to find it [#where-to-find-it]

Open a project, then click the **Analytics** icon (a small bar-chart) in the
project's header, next to the view switcher.

{/* screenshot: the project header with the Analytics icon highlighted */}

## Who can see it [#who-can-see-it]

* The whole page needs the &#x2A;*`analytics:view`** permission on the project. If
  you don't have it, orboto shows "You don't have access to this project's
  analytics" instead of the page. Ask a project admin to grant it.
* Money figures - the **Actual cost** summary tile, the **Budget** card, the
  **Loaded member cost** card, and **Earned Value*&#x2A;'s money mode - need the
  separate &#x2A;*`budget:view`** permission. Without it, those cards simply don't
  render; everything else on the page still does.
* External guest accounts cannot open project analytics at all, regardless of
  permissions - the aggregates would leak counts from milestones that aren't
  shared with them.

This page groups the charts by topic across five linked chapters. This page
covers the always-visible top of the dashboard; the rest continue below.

## Controls that apply across the page [#controls-that-apply-across-the-page]

{/* screenshot: the analytics header showing the date-range picker and the Summarize project button */}

* **Date range picker** (top right: Last 7/30/90 days, This quarter, Year to
  date, All time, or a custom From/To pair). It only affects some of the
  charts - see the table below. Changing it does not reload the whole page;
  each card that listens to the range re-fetches on its own.
* **Milestone selector.** A dropdown lives inside the **Burndown** card, but
  it is not local to burndown: picking a milestone there also re-scopes the
  **Delivery forecast**, **Human + agent collaboration**, and **Earned
  Value** sections further down the page to that milestone. Leaving it on
  "All milestones" scopes those the same way, to the whole project.
* **CSV** button on most cards - downloads that card's underlying data as a
  CSV file, for pasting into a spreadsheet or another tool. Each card exports
  independently; there is no single "export everything" button.
* **Summarize project** (top right, sparkle icon) - asks the AI assistant for
  a one-off written paragraph summarizing the project's current state. Only
  shown when your workspace has AI configured. See
  [AI assistant](/user-guide/ai-assistant).
* The **gear icon** (top right, only if you can edit the project) jumps
  straight to the project's settings, where budgets and rates are configured.

Which cards actually listen to the date-range picker:

| Card                                                                                                | Scoped by the range picker?                                                                                                        |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Overview numbers                                                                                    | No - always lifetime totals                                                                                                        |
| Burndown                                                                                            | No - scoped only by the milestone selector                                                                                         |
| Velocity                                                                                            | Yes                                                                                                                                |
| Cycle time                                                                                          | Yes                                                                                                                                |
| Workload                                                                                            | Yes (falls back to the current week if you leave the picker on its default)                                                        |
| Loaded member cost                                                                                  | Yes                                                                                                                                |
| Human + agent collaboration                                                                         | Yes, and by the milestone selector                                                                                                 |
| Flow & lead time, Delivery forecast, Flow metrics, Bottleneck & predictability, Estimation accuracy | No - each uses its own fixed lookback window, described on the [Flow, cycle time and forecasting](/user-guide/analytics-flow) page |
| Budget, Earned Value                                                                                | No - both work from the project or milestone's whole life, not a window                                                            |

If a number on this page doesn't match a number on another, check this table
first - a common misreading is assuming every chart shares one clock.

## Overview numbers [#overview-numbers]

Four tiles at the very top of the page:

* **Total tickets** - every ticket in the project, any status.
* **Estimated time** - the sum of every ticket's time estimate.
* **Logged time** - the sum of every time entry ever logged on the project.
* **Actual cost** (needs `budget:view`) - those logged hours priced at each
  contributor's hourly rate (see [Budget and cost tracking](/user-guide/analytics-budget)
  for exactly how a rate is resolved).

These are lifetime totals - the date-range picker does not affect them.

## Burndown [#burndown]

{/* screenshot: the burndown chart with the actual line against the ideal line */}

The burndown chart shows, over time, how many tickets are still open (not
`WONT_FIX`, not done) against an **ideal line**.

* **Open** (solid line) - open ticket count on that day.
* **Total** (dashed grey line) - every ticket that existed by that day
  (open or closed), so you can see scope grow.
* **Ideal** (dotted line, only shown when you pick a specific milestone with
  both a start and an end date) - a straight line from the milestone's peak
  ticket count at its start down to zero at its end. It is not a prediction;
  it is the reference line for "if we closed tickets at a perfectly constant
  rate, this is where we'd be."

**How to read it:** if the Open line sits **above** the Ideal line, you're
behind that pace; below it, you're ahead. A line that tracks the ideal
closely is healthy; a line that flattens out (stops dropping) while Total
keeps climbing means new work is arriving faster than it's closing.

Use the dropdown above the chart to scope to one milestone (this also
enables the ideal line) or leave it on "All milestones" for the whole
project's history, anchored to the earliest ticket's creation date. The
X-axis groups by day, week, or month automatically depending on how long the
window is (day up to 60 days, week up to a year, month beyond that).

## Velocity [#velocity]

{/* screenshot: the velocity bar chart, closed tickets per week */}

A bar per week showing how many tickets **closed** that week (again
excluding `WONT_FIX` - scope that was cut isn't "delivered"). Scoped by the
date-range picker; with no range selected it shows the last 8 weeks.

**How to read it:** a roughly even bar height week to week means your team's
throughput is predictable, which makes "how much can we commit to next
sprint" a safer question to answer. A jumpy, spiky pattern (a big bar
followed by near-zero) is a signal to look at what caused the spike - a
batch of small tickets closed together inflates a single week without
reflecting a real capacity change.

## Workload [#workload]

{/* screenshot: the workload table with assigned, logged and capacity columns */}

One row per project member:

* **Assigned** - open (not-done) tickets currently assigned to them in this
  project. Not scoped by the date-range picker - it's a snapshot of right
  now, regardless of which range you picked.
* **Logged** - time they logged in the selected range (or lifetime, if you
  picked "All time").
* **Capacity** - logged hours in the range as a percentage of their expected
  hours for that many days, derived from their weekly capacity (set on their
  user profile). Shown in red above 100%. A member with no weekly capacity
  set shows a dash instead of a percentage - there's nothing to compare
  against.

This table is **project-scoped**: it only shows time and assignments inside
this one project. For a person's workload **across every project they're
on**, use the workspace-wide [Capacity](/user-guide/planning/capacity)
page instead - the two intentionally answer different questions.

## Troubleshooting [#troubleshooting]

* **"You don't have access to this project's analytics."** You're missing
  `analytics:view` on this project. Ask a project admin to grant it - this is
  not something you can self-serve.
* **The Actual cost tile, Budget card, or Loaded member cost card are just
  missing (not empty - absent).** You have `analytics:view` but not
  `budget:view`. Ask a project admin for the additional permission if you
  need to see money figures.
* **Burndown is empty / has no ideal line.** An empty chart means the
  project (or the selected milestone) has no tickets yet. A missing ideal
  line means the selected milestone has no start date, no end date, or both
  * set them in the milestone's details.
* **A number changed after I picked a different date range, but another
  number on the same page didn't.** Expected - see the scoping table above.
  Not every card listens to the range picker.
* **Guest / external account gets a 403 opening this page.** By design -
  external guests cannot see project analytics at all, even with permission,
  because the aggregates would leak private-milestone counts they shouldn't
  see.

## Where to go next [#where-to-go-next]

<Cards>
  <Card title="Flow, cycle time and forecasting" href="/user-guide/analytics-flow" description="Cycle time, lead time, delivery forecasting, WIP and bottlenecks." />

  <Card title="Estimation, collaboration and activity" href="/user-guide/analytics-team" description="How accurate estimates are, how humans and agents split the work, and git activity." />

  <Card title="Budget and cost tracking" href="/user-guide/analytics-budget" description="Configured budgets, per-person cost, and loaded cost including AI usage." />

  <Card title="Earned Value Management" href="/user-guide/analytics-earned-value" description="Whether your spend and schedule bought the progress they should have." />

  <Card title="Capacity planning" href="/user-guide/planning/capacity" description="Workload across every project a person is on, not just this one." />

  <Card title="Requirements documents" href="/user-guide/knowledge/requirements-documents" description="Turn this project's data into a customer report or a requirements specification." />
</Cards>


# Customers and guests (/user-guide/customers-and-guests)



orboto lets you bring people from outside your team into the right slice of a project - a client, a contractor, a stakeholder - without exposing everything. This chapter covers the **Customers** area (for organising external relationships) and what the experience looks like for a **guest** or **external** user.

## Customers [#customers]

If you have customer-management permission, **Customers** appears in the sidebar. A **customer** is an external organisation you work with, used to group projects and the external people tied to them.

{/* screenshot: the customers list with customer cards showing project and member counts */}

* **Add a customer** with just a name to start - the rest can be filled in afterwards.
* Each card shows how many **projects** and **members** are associated, and an inactive badge once archived.
* **Archive** a customer you no longer work with (and **reactivate** later); use the show-inactive toggle to see archived ones. Search by name to find one quickly.

### Inside a customer [#inside-a-customer]

Opening a customer gives you four tabs:

* **Overview** - name, logo, default hourly rate (used when generating a [customer report](/user-guide/knowledge/requirements-documents) priced in money), billing address, a primary contact person, and free-text notes.
* **Members** - the external people tied to this customer. Create at least one customer-scoped **role** first (on the Roles tab), then **invite** a new person by email or **add** an existing user. **Sync members to all projects** copies the current member list onto every project linked to this customer in one action - handy after adding someone new.
* **Roles** - customer-scoped roles that decide what a member of this customer can do across its projects.
* **Projects** - the projects linked to this customer.

Customer-scoped invitations mean external contacts land with exactly the access their customer role grants, on every project tied to that customer - not project by project.

## What guests see [#what-guests-see]

Guest and external users get a deliberately narrow experience:

* Their home screen is a simple list of just the **projects** and **doc spaces** shared with them - not the full dashboard.
* They see only the tickets and milestones that have been opened to guests (see below), plus tickets they created themselves.
* Internal-only areas (Timesheets, Absences, Capacity, Admin, and so on) are hidden entirely.

{/* screenshot: the external/guest home screen listing shared projects and spaces */}

## Opening a project to guests [#opening-a-project-to-guests]

Guest visibility is controlled **per milestone**, not with one project-wide switch:

1. Open a milestone's edit dialog and turn on **visible to guests**. Every non-private ticket inside that milestone becomes visible to guest and external users.
2. A ticket a guest created themselves is always visible to them, even outside a guest-visible milestone.
3. In the project's **Settings**, two further toggles narrow what a guest sees on an individual ticket: hide **private tickets** from guests (governs the single-ticket view specifically - lists and search already hard-exclude private tickets from guests regardless of this setting), and hide **comments** from guests.

{/* screenshot: the milestone edit dialog with the "visible to guests" toggle, and the project settings guest-access toggles */}

To preview exactly what an external user will see, use the **Guests** filter toggle on the project's filter bar - it narrows the board to tickets a guest could actually see (see [Projects and tickets](/user-guide/work/projects-and-tickets)).

## Inviting people [#inviting-people]

When inviting someone to a project, choose whether they join as a regular **member** or as a **guest** - guests are automatically held to the narrower view above regardless of what role they're given. Invitations are sent and managed by workspace administrators (in the admin area), or by anyone with the right permission straight from a project's **Settings**.

## Troubleshooting [#troubleshooting]

* **A guest still can't see a ticket I expect them to.** Check that its milestone has **visible to guests** turned on, and that the ticket itself isn't marked private - private tickets stay hidden from guests everywhere, independent of the settings toggles.
* **I can't add a member to a customer.** Create at least one customer-scoped role on the Roles tab first - the Members tab blocks adding people until one exists.
* **A newly added customer member doesn't show up on the projects.** Use **Sync members to all projects** on the Members tab - adding someone to the customer doesn't automatically touch already-created projects.
* **I don't see the Customers item in the sidebar.** It only appears with customer-management permission - ask a workspace administrator.


# User guide (/user-guide)



orboto covers the full lifecycle of team work: planning, tracking,
discussing, timing, and reporting. Each chapter below explains one area and
how to use it day to day.

<Cards>
  <Card title="Projects and tickets" href="/user-guide/work/projects-and-tickets" description="Boards, lists, Gantt, workflows, labels, dependencies." />

  <Card title="Docs and wiki" href="/user-guide/knowledge/docs-and-wiki" description="Rich-text pages, smart links, backlinks, the LLM wiki." />

  <Card title="Time tracking" href="/user-guide/planning/time-tracking" description="Timers, timesheets, absences, the time calendar." />

  <Card title="Planning and alerts" href="/user-guide/planning/planning-and-alerts" description="Milestones, versions, capacity, budgets, alert rules." />

  <Card title="Analytics" href="/user-guide/analytics" description="Charts, reports, portfolio views, earned value." />

  <Card title="Dashboard" href="/user-guide/everyday/dashboard" description="Your customizable widget start page." />

  <Card title="Search" href="/user-guide/knowledge/search" description="Global search and the OQL query palette." />

  <Card title="Notifications" href="/user-guide/everyday/notifications" description="In-app, email, Discord and Telegram delivery." />

  <Card title="Customers and guests" href="/user-guide/customers-and-guests" description="External access with scoped permissions." />

  <Card title="Requirements documents" href="/user-guide/knowledge/requirements-documents" description="Structured specs linked to tickets." />

  <Card title="AI assistant" href="/user-guide/ai-assistant" description="The in-app chat that operates orboto for you." />
</Cards>


# Agents administration (/admin/ai/agents)



When AI agents work in your workspace - via MCP, the CLI, or an
autonomous fleet - three admin surfaces give you the operational
controls: **Admin -> Multi-Agent** (onboarding, live presence, pausing),
**Admin -> Agent rules** (the binding instructions every agent receives),
and **Admin -> Agent drift** (a monitor for work that slipped outside the
normal ticket/commit workflow).

## Personal accounts vs. service accounts [#personal-accounts-vs-service-accounts]

Before onboarding anything, it helps to know which kind of account you
actually need - orboto models two distinct things:

* **Your personal account** - you, signed in through the web app, or an
  AI client you're driving interactively (Claude Desktop, Cursor, VS
  Code). One person, one identity. Authenticates via your normal login
  (including SSO) or a personal API key scoped to you.
* **A service account** - a shared identity for running coding agents
  *unattended*: one agent, or several running in parallel (for example
  multiple Claude Code or Codex sessions each working a different
  ticket at once). Authenticates via a single API key every instance
  shares - orboto tells the individual instances apart by a per-instance
  session, not by separate logins. Use a service account whenever
  nobody is watching the agent work, or whenever you want more than one
  agent running concurrently.

This distinction also decides how **timers** behave: your personal
account has one timer - starting a new one replaces and books whatever
was already running, so you never end up with an orphaned clock. A
service account instead runs **one independent timer per agent
instance** - nothing auto-stops another instance's timer, which is
exactly what lets several agents track time correctly against different
tickets at the same time.

## Onboarding a service account (guided setup) [#onboarding-a-service-account-guided-setup]

{/* screenshot: Admin - Multi-Agent page, the four-step guided setup card */}

**Admin -> Multi-Agent** leads with a **Guided setup: parallel agents**
card that walks through the whole thing in order - you need permission
to manage users to run it:

1. **Create or pick a service account.** Either create a brand-new one
   (name + email, e.g. "Codex Fleet" / `codex-fleet@yourteam.example`)
   or search for and reuse an existing service account you've already
   set up.
2. **Assign the agent role.** The role needs the `api:use` and `mcp:use&#x60;
   permissions so the account (and every agent instance using it) can
   actually authenticate. The card recommends the built-in
   &#x2A;*`service-account`** role, which already includes both.
3. **Mint the API key** (optional - only needed if your coding agent
   can't complete an OAuth login on its own; step 4 covers the OAuth
   path instead). Name the key something you'll recognize later. It's
   shown **once**, immediately after creation, with a copy button - copy
   it now and store it somewhere safe, since orboto never displays it
   again.
4. **Hand off to your coding agent.** Generate a setup prompt for this
   account, then paste it directly into your coding agent's chat - the
   agent wires up its own orboto access from there (via the API key from
   step 3, or by completing its own OAuth login if it's capable of that).

Each step visibly marks itself done as you complete it, and later steps
stay disabled/greyed out until the one before it is finished, so there's
no way to mint a key for an account that doesn't exist yet or assign a
role before picking who it's for.

## Live presence [#live-presence]

{/* screenshot: Admin - Multi-Agent page, presence table with lease + claim pills */}

Below the guided setup, the **presence table** shows every currently
active agent session - a session counts as active if it's sent a
heartbeat within the last 90 seconds; older ones simply disappear from
the list rather than sitting there stale. Filter with the **All / Bots
only / Humans only** chips above the table. Each row shows:

* **User** - the account's name/email, with a bot or person icon.
* **Runtime** - the connecting client's self-reported name and version
  (e.g. `claude-code v1.x`).
* **Status** - working, blocked, or idle, plus a **paused** badge if
  either that specific bot or the whole workspace is currently paused
  (see below).
* **Working on** - the ticket it currently holds, if any, plus a row of
  small badges for every **work-session lease** it holds (a ticket key
  and role, e.g. "ACME-42 - implementation", with the lease's expiry
  shown on hover) and a lock-icon count of any **resource claims** it's
  granted or waiting on for that lease - useful for spotting a stuck
  agent that's actually blocked waiting on a file-path claim someone
  else is holding.
* **Capabilities** - tags the agent declared about itself.
* **Last seen** - time of its most recent heartbeat.

## Work routing labels [#work-routing-labels]

Two ticket labels steer which tickets an autonomous agent picks up on its
own - the full model (pull semantics, review lanes, feeding a fleet) is
covered in [Work routing and fleets](/agents-ai/work-routing); the
short version, shown right on this admin page next to the pause switch:

* **`human`** - a hard lock. Agents never pull this ticket on their own.
  A human can still explicitly hand it to an agent, which then sees a
  clear warning that it's working reserved work.
* **`agent:<tag>`** - a preference, not exclusivity. Agents pulling with
  that specific tag get first crack at the ticket; other agents still
  take it if nothing better is available. A ticket with no label at all
  is open to any agent by default (opt-out, not opt-in).

## Pausing [#pausing]

Two independent switches stop self-directed agent work, both visible on
the Multi-Agent page:

* **Per-bot pause** - a Pause/Resume icon next to any bot's status badge
  in the presence table stops just that one agent identity from pulling
  new work on its own; anything already explicitly assigned to it keeps
  running. The same toggle is also available per-bot in the user editor
  under Admin -> Users.
* **Workspace-wide pause** ("Autonomous work") - one switch at the top of
  the Multi-Agent page stops **every** agent's self-directed pulls at
  once, instantly. This is the one to reach for during a maintenance
  window or an incident - explicitly assigned work still runs even while
  paused; only agents picking up NEW work on their own initiative stops.

## Agent rules [#agent-rules]

{/* screenshot: Admin - Agent rules page, a rule block with the targeting panel open */}

**Admin -> Agent rules** manages the binding working-rules every external
coding agent (Claude Code, Cursor, headless bots, any MCP client working
in a repo) receives when it connects or runs `orboto init`. This is
distinct from the [AI Chat assistant](/admin/ai/chat-assistant),
which runs on its own fixed internal prompt and never reads these rules.

Each rule is a block with a title and body text. Per rule:

* **Reorder** with the up/down arrows on the left - order matters, since
  rules are assembled into one document in this order.
* **On/off checkbox** - a disabled rule is skipped entirely when
  assembling what an agent receives.
* **Edit the title inline**, and the **body** in the textarea below it
  (saves when you click away).
* **Targeting** (the crosshair icon) opens a panel to scope a rule so it
  only applies to specific **agent kinds** (suggested values: `coding`,
  `orchestrator`, `reviewer`, `runner`, `chat`) and/or **model tiers**
  (`frontier`, `standard`, `small`) - leave both empty for "everyone."
  You can type your own values beyond the suggestions too. A rule with
  any targeting shows a small amber tag summarizing it right in the list,
  so you can spot scoped rules at a glance without opening every panel.
* **Per-tier body variants** - inside the same targeting panel, give a
  specific model tier its own alternate wording that replaces the
  default body just for that tier (e.g. a shorter, more directive
  version for a "small" model, and a fuller explanation for "frontier").
  Leave a tier's variant blank to fall back to the default body.
* **Reset to default** (the built-in rules only, marked "default" in the
  list) restores the original shipped wording, discarding any edits.
  **Delete** (custom rules you added yourself, marked "custom") removes
  it entirely.

**Preview** (top-right) shows exactly what gets assembled and sent -
pick a specific agent kind and/or model tier from the two dropdowns
above the preview to see precisely what THAT combination would receive,
rather than guessing from the individual rule rows.

Click **Add rule** at the bottom to write a workspace rule of your own
from scratch, the same way you'd add a custom instruction anywhere else

* give it a title and body text, save, and it's live for the next agent
  that connects.

A drift monitor (below) separately flags workflow drift, not
rules-acknowledgment - see the next section.

## Agent drift [#agent-drift]

{/* screenshot: Admin - Agent drift page, metrics summary + filtered event list */}

**Admin -> Agent drift** tracks moments where a commit or a ticket
transition happened **outside** orboto's normal tracked workflow -
useful for catching an agent (or a human) that bypassed the
ticket/timer/commit-message discipline the rest of the product assumes.
It watches two specific patterns:

* **Untracked commits** - a commit that referenced no ticket key AND
  wasn't covered by a running timer or time-entry window at the time it
  landed.
* **Transitions without a summary** - a ticket's status changed with no
  accompanying summary comment from whoever made the change.

This feature is **opt-in**: nothing gets recorded until an admin sets
`system_config.agent_drift_detection_enabled` to `true`. There's no
dedicated toggle for this in the System Settings UI yet - set it via the
system-config API/PATCH directly. Once it's off, existing recorded
events stay visible on this page (marked historical); once it's on,
detection resumes going forward - a banner at the top of the page tells
you plainly which state you're in.

The page opens with a **metrics summary**: total events, a breakdown by
type (untracked commits vs. transitions-without-summary), and a **Top
drifters** panel naming the three users/bots with the most events - a
fast way to spot a single misbehaving agent identity rather than
scrolling the full list.

Below that, filter by **type** and by **status** (Open / Resolved / All).
Each row shows when it happened, who did it (with a "bot" tag if it was
an agent identity), and the specific event - a commit's SHA, message and
repo for a commit-drift row, or a link straight to the ticket for a
transition-drift row. Status shows **Open** (nothing done about it yet),
**Resolved** (someone reviewed and dismissed it), or &#x2A;*Retro `<ticket
key>`** (the drift was already covered by a retrospective ticket someone
filed for it, linked right there). Click the checkmark on any open row
to **mark it resolved** once you've reviewed it - there's no bulk-resolve,
each row is a deliberate decision.

## Troubleshooting [#troubleshooting]

* **A specific agent never shows up in the presence table** - it hasn't
  sent a heartbeat in the last 90 seconds, or it never authenticated
  successfully in the first place; re-check the API key/OAuth wiring
  from the guided-setup handoff rather than assuming the table itself is
  broken.
* **An agent keeps ignoring the `human` label** - that label is a hard
  lock against *self-directed* pulls only; if a human explicitly assigned
  the ticket to that agent, it will still work it (with a warning shown
  to it) - check the assignment, not just the label.
* **Pausing a single bot didn't stop it from finishing what it was
  already doing** - expected; both pause switches stop *new*
  self-directed pulls, they never interrupt work already in progress or
  explicitly assigned.
* **An agent doesn't seem to be following a rule you just added** -
  check whether the rule is scoped via **Targeting** to an agent kind or
  model tier that doesn't match this particular agent; use **Preview**
  with that exact kind/tier combination to see precisely what it
  actually receives.
* **Agent Drift shows nothing even though you're sure agents are
  committing without ticket keys** - confirm
  `agent_drift_detection_enabled` is actually set to `true`; it's off by
  default and has no UI toggle today, so it's easy to assume it's
  already on when it never was.
* **A drift event you already handled keeps showing as Open** - resolving
  is a manual, per-row action with no automatic detection of "someone
  fixed this"; click the checkmark yourself once you've reviewed it, or
  file a retro ticket and it'll show as linked instead.


# AI providers and models (/admin/ai/ai)



**Admin -> AI settings** is the one place every AI feature in orboto
reads its provider, model and cost configuration from - summaries,
duplicate detection, semantic search, translation, and the
[AI Chat assistant](/admin/ai/chat-assistant).

## Picking a provider [#picking-a-provider]

{/* screenshot: AI settings page, the three provider cards (orboto AI / Own provider / Disabled) */}

Three cards lead the page - **clicking a card only previews it**, it
does NOT switch anything yet. A previewed card shows a note ("Just
looking - nothing changes until you activate. Your current setup keeps
running...") and its own explicit activation button - only clicking that
button actually switches the live provider. This means you can safely
click through all three cards to see what each one asks for before
committing to anything:

* **orboto AI** (recommended) - hosted in the EU, works out of the box on
  a managed (Coolify/cloud-hosted) tenant with no key to paste at all;
  usage is billed pay-as-you-go from your subscription wallet. On
  self-host without a managed subscription, you paste a key from your
  orboto account instead - still no base URL or other wiring to figure
  out. Click **Activate orboto AI** to switch to it.
* **Own provider** - bring your own key. A dropdown lets you pick OpenAI,
  Anthropic (Claude), Google Gemini, GitHub Copilot (Business/Enterprise
  seat only - an individual Copilot subscription violates its terms of
  service for this kind of use), Ollama (self-hosted, no key needed at
  all), or any OpenAI-compatible endpoint (OpenRouter, Groq, DeepSeek, LM
  Studio, vLLM, and others). Picking a provider here reveals a &#x2A;*Switch
  to `<provider>`** button - nothing changes until you click it, even
  after picking from the dropdown. For OpenAI-compatible or Anthropic
  providers, a **preset picker** appears that autofills the base URL and
  a sensible default model for known vendors, saving you from typing a
  raw API endpoint by hand.
* **Disabled** - no AI features anywhere in the workspace. Click
  **Turn AI features off** to confirm.

Switching providers (either direction) is **lossless**: the outgoing
provider's base URL, key and model are stashed server-side, so switching
back later restores exactly what you had configured before, rather than
making you re-enter it from scratch.

This choice covers **chat and completion** features only - embeddings
have their own independent provider below, so switching one never
switches the other. A common combination: Anthropic for chat (it has no
embeddings endpoint at all) with orboto AI or OpenAI for embeddings.

## Default model [#default-model]

Once a provider is wired up, **Load models** fetches its live model
catalog into a searchable picker; providers with no catalog endpoint
accept a typed model id instead. An optional **vision model** routes any
call carrying image attachments to a multimodal model even when the
default model is text-only - useful to keep a cheap default while still
supporting image attachments in AI Chat. **Allowed chat models**
(comma-separated ids) lets end users pick among a curated set inside the
chat drawer; leave empty to hide that picker and always use the default.

## Per-feature model overrides and answer length [#per-feature-model-overrides-and-answer-length]

Every AI operation orboto runs (grouped as classifiers, summarization,
content rewriting, chat/reasoning, and utility) can override the default
model - useful for a cheap, fast model on classification and a stronger
one for chat or RAG. Each override also has its own **answer length**
budget (how many tokens the operation may write back), offered as
plain-language presets - Short, Standard, Long, Very long - each a
multiple of that operation's own default, with a numeric override for
advanced tuning. If a feature's replies come back empty, its budget is
likely too small to leave room for both a reasoning model's silent
"thinking" and the visible answer - try Long or Very long first.

## Rate limit [#rate-limit]

**Requests per user per minute** caps how often one person can call an AI
feature; the default is 30.

## Embeddings and reindexing [#embeddings-and-reindexing]

{/* screenshot: AI settings - embedding migration modal (rebuild vs start fresh) */}

Vector-based features (semantic search, duplicate/related detection,
Ask-Docs) need an embedding provider, independent of the chat provider
chosen above. Scroll down to the **Embeddings** subsection:

* On a **managed tenant**, two buttons let you choose &#x2A;*Use orboto AI
  (managed)** (the default - billed from your subscription wallet, zero
  configuration) or **Bring your own provider**. Picking "bring your own"
  reveals the same kind of provider dropdown as the chat section above -
  OpenAI, Google Gemini, Ollama, or OpenAI-compatible (Anthropic is
  absent here on purpose - it has no embeddings endpoint to configure).
* On **self-host without a managed subscription**, the provider dropdown
  is the only option - pick one directly and fill in its base URL/key/
  model, the same as the chat section.

A **Load models** button here works the same way as on the chat section,
scoped specifically to embedding-capable models on the chosen provider.

Changing the embedding provider or model can change the vector size the
index needs to store. When that happens, an unblockable modal appears
with two recovery paths: **Rebuild now** clears and re-creates every
vector for every ticket, comment and doc (search features are empty until
it finishes), or **Start fresh** switches immediately and lets vectors
refill gradually as content changes (faster, but search stays partially
empty for longer). If the new model's vectors are larger than what the
search index can store at all, neither option can proceed - the fix is to
pick a smaller-dimension model in the settings behind the modal.

## AI Usage [#ai-usage]

**Admin -> AI Usage** reports total calls, input/output tokens, and
errors, plus a daily-calls chart, per-user and per-operation breakdowns, a
"Top AI Chat users" table, and a recent-failures list - the place to check
before assuming a provider issue is a orboto bug.

## Troubleshooting [#troubleshooting]

* **"Load models" fails or returns nothing** - a wrong base URL or an
  invalid/expired key is the most common cause; the error shows inline
  and you can still type a model id manually while you fix the wiring.
* **Chat model list is empty but embeddings still work** - some managed
  plans include embeddings only; switch the chat card to "Own provider"
  with your own key while keeping the included embeddings unchanged.
* **The default model looks like an embedding model** - a stale value
  from an old default surfaces a visible warning on this page; chat calls
  cannot work with an embedding model, clear it or pick a real chat model.
* **A feature's answers come back empty or truncated** - raise its answer
  length preset (Long / Very long) before assuming the model is broken;
  reasoning models spend part of the budget thinking before they answer.
* **Reindex modal won't go away** - it stays open on purpose while the
  schema and the live provider disagree on vector size; pick Rebuild or
  Start fresh (or fix the model setting first, if the size exceeds what
  the index can hold at all - that state explains itself in the modal).


# AI Chat assistant (/admin/ai/chat-assistant)



The in-app AI Chat lets a user run orboto operations by talking to an
assistant instead of clicking through the UI. It opens as a right-side
drawer from the Sparkles icon in the top bar, or the Cmd/Ctrl+J shortcut.
The assistant answers read-only questions on its own (search, "what's
overdue on this project", "summarize this ticket"), and can also perform
write actions - comment, assign, move, create - but only after the user
explicitly approves each one. A destructive action (delete) always
requires the user to type the exact ticket key to confirm, regardless of
any other setting.

The important guarantee for an admin evaluating this feature: every tool
the assistant runs executes **as the logged-in user**, through the exact
same REST routes and permission gates the regular UI uses. The assistant
can never do anything that specific user couldn't already do by clicking
through the app themselves - it's a different input method, not a
privilege escalation.

## Turning it on [#turning-it-on]

Three separate things must all be true before any user sees the chat
button at all:

1. **An AI provider is configured.** Admin -> AI settings -> pick a
   provider and a model (see
   [AI providers and models](/admin/ai/ai)). The chat reuses
   whichever provider powers the rest of orboto's AI features - there is
   no separate provider just for chat.
2. **The workspace flag is on.** Admin -> System settings -> General ->
   "In-app AI Chat assistant". Off by default. While off, the chat is
   unavailable for absolutely everyone in the workspace - the button
   doesn't render, and the underlying API endpoint itself returns 403 if
   called directly.
3. **The user holds the `ai:chat:use` permission.** Granted by default to
   the `super-admin`, `project-admin`, and `developer` roles. To let
   anyone else use it, add the permission to their role under Admin ->
   Roles. A user without it sees no chat button and no keyboard shortcut
   at all - the feature is invisible to them, not merely disabled.

All three gates are independent - missing any one of them hides the
feature completely for the affected users, so if a specific person can't
see the chat, check all three in order rather than assuming it's the
provider.

## What a user can do with it [#what-a-user-can-do-with-it]

* Ask read-only questions - search, summaries, status lookups - answered
  directly, no approval needed.
* Ask it to take a write action (comment on a ticket, assign someone,
  move a ticket, create a new one). Unless the user has turned on
  auto-approve (below), each write shows a confirmation prompt with
  exactly what it's about to do before it runs.
* Ask it to delete something. This always requires typing the ticket key
  to confirm, even with auto-approve on - there is no setting that
  removes this specific confirmation.
* Attach an image to a message, if &#x2A;*AI Chat image attachments (vision)**
  is enabled (Admin -> AI settings) and the configured model actually
  supports vision - see the AI settings page for the exact requirement.
* Pick from a curated model list mid-conversation, if the admin
  configured **Allowed chat models**; otherwise every conversation uses
  the workspace's default chat model.
* Resume a previous conversation, or delete individual conversations /
  clear all history, from the drawer's Conversations panel.

## Per-user options [#per-user-options]

In &#x2A;*Profile -> "Auto-approve AI Chat write actions"** (off by default),
a user can opt themselves into skipping the per-action approval prompt
for write actions - useful for a power user who trusts the assistant and
doesn't want to click "approve" on every single comment it posts.
Destructive actions still always require the typed-key confirmation
regardless of this setting. Every auto-approved execution is marked as
such in the audit log, so turning this on for yourself doesn't reduce
what an admin can review afterward - it just removes the interactive
prompt.

## Cost controls [#cost-controls]

* **Daily token cap per user** (Admin -> System settings -> "AI Chat
  daily token cap per user"). `0` or empty means no cap. When set to a
  number, a user who spends more than that many tokens (prompt +
  completion combined) on AI Chat within one UTC day gets a "limit
  reached" message for the rest of that day - it resets at UTC midnight,
  not on a rolling 24-hour window.
* Conversations themselves are stored indefinitely (so users can resume
  them later) until the user deletes them - there's no separate
  conversation-count cap, only the token cap above.

## Auditing and usage [#auditing-and-usage]

* Every tool the assistant executes writes an `ai.chat.tool_call` row to
  the audit log, with `auto_approved: true` recorded whenever the
  per-user auto-approve setting skipped the confirmation prompt for that
  specific call. Approve and cancel decisions themselves are also logged
  separately (`ai.chat.tool_call.approved` / `.cancelled`), so you can
  reconstruct exactly what was proposed vs. what actually ran.
* Token usage for chat shows up in **Admin -> AI Usage** as its own
  `chat.turn` operation row, alongside a "Chat conversations" count and a
  "Top AI Chat users" table - the place to look if you suspect one
  account is driving disproportionate AI spend.

## How the tool set is scoped (for maintainers) [#how-the-tool-set-is-scoped-for-maintainers]

The chat's available actions are a deliberately **curated subset** of
everything orboto's automation surfaces (MCP, the API) can do - not
every possible operation is exposed to the in-app assistant, only the
ones that map cleanly onto something a chat user would naturally ask
for. If you're building or extending an internal integration and wonder
why the chat can't do something the MCP server can, that's usually by
design rather than a gap to report.

## Troubleshooting [#troubleshooting]

* **Chat button doesn't appear for anyone** - check the three enable
  gates in order: is a provider actually configured and working (test it
  on the AI settings page), is the workspace flag on, and does at least
  one role have the permission. Missing any one of the three hides it
  workspace-wide or for that specific role.
* **Chat button appears for admins but not regular users** - almost
  always the `ai:chat:use` permission; it's only granted by default to
  super-admin, project-admin, and developer roles, so add it explicitly
  to any other role under Admin -> Roles.
* **A user hits "limit reached" mid-workday** - they've exceeded the
  daily token cap; it resets at UTC midnight, not 24 hours after their
  first message, so someone starting late in their own timezone can hit
  a cap that feels like it reset "too early" relative to their local
  day.
* **A write action ran without a confirmation prompt and the user is
  surprised** - check whether they turned on auto-approve in their own
  Profile; it's per-user and off by default, so this is either a setting
  they forgot enabling, or a genuine question worth asking them directly.
* **Wondering exactly what the assistant did in a session** - the audit
  log is the source of truth: filter for `ai.chat.tool_call` entries
  around the time in question, which show the exact tool, its
  parameters, and whether it was auto-approved.


# Git integration (/admin/data/git-integration)



Connect a repository and orboto keeps tickets and code in sync: commits
and pull requests that mention a ticket key appear on the ticket
automatically, and pull-request state (open / merged / closed) updates
itself as the PR progresses. All communication is HTTPS REST - orboto
never clones the repository or pushes to it, and no SSH access to your
Git host is required (except for the dedicated SSH-poll connection type,
covered below).

Setting this up is two separate jobs, done by two different people in a
larger org:

1. **Workspace setup** (Admin -> Git integration) - a one-time,
   instance-wide step where a workspace admin registers the credentials
   every project's connections will reuse: a GitHub App and/or a GitLab
   OAuth application.
2. **Per-project connection** (each project's own Settings -> Git tab) -
   a project owner connects that specific project's repository, using
   either the workspace app from step 1 or a manually pasted token.

You need step 1 done (by an admin) before step 2 becomes the easy path;
step 2 also works entirely on its own with a manual token, for any
provider, even if nobody has set up an App at all.

## Step 1 - workspace setup (Admin -> Git integration) [#step-1---workspace-setup-admin---git-integration]

{/* screenshot: Admin - Git integration page, GitHub App card + GitLab OAuth card */}

Open **Admin -> Git integration**. The page has two independent sections

* set up either or both, depending on which Git hosts your teams actually
  use.

### GitHub - the one-click App flow [#github---the-one-click-app-flow]

Click **Connect GitHub App**. This does NOT ask you to fill in any
fields yet - it takes you straight to github.com to confirm the App's
name. GitHub then redirects you back to orboto, which automatically:

* fills in the App's required permissions and webhook URL from a
  manifest orboto generated for you,
* receives and stores the App ID, private key and webhook secret GitHub
  issued,
* shows a success banner with the App's slug once it lands back on this
  page.

You never see or copy an App ID, a PEM private key, or a webhook secret
by hand with this path - that's the entire point of it.

If an App is already configured, the same button reads **Re-register
GitHub App** instead - clicking it replaces the stored credentials with a
freshly generated App. The OLD App registration on github.com is left
in place untouched; if you don't need it anymore, go uninstall it
manually on GitHub's side (orboto has no way to reach in and remove it
for you).

**Advanced: configure manually** is a collapsed panel below the App card,
for anyone who'd rather register the GitHub App by hand on github.com and
paste the results in themselves:

* **GitHub App ID** - the numeric ID from the App's registration page.
* **GitHub App slug** - the URL-safe handle from the App's URL (used to
  build the install link shown to project owners).
* **GitHub App private key (PEM)** - paste the full `.pem` file GitHub
  gave you when you created the App. It's shown as a large text box;
  after saving, the field goes blank again (the stored value is masked,
  not re-displayed) - pasting a new value and saving replaces it, leaving
  it empty and unsaved keeps the old key.
* **GitHub App webhook secret** - the shared secret you set on the App's
  webhook config on GitHub's side. Same masked-on-read behavior.
* **Disable GitHub App flow** - a checkbox. When on, the GitHub App card
  disappears from every project's "Add connection" picker workspace-wide,
  even though the credentials stay saved. Use this during a planned
  migration or an incident, without losing the configuration.

After either path, click **Validate connection**. orboto pings GitHub
with the stored credentials and, on success, shows the App's name, its
owner (with account type), and a link to the App's page on github.com -
proof the credentials actually work, not just that they were saved.

If you are a super-admin, a third control appears once an App is
configured: **Sync installations from GitHub**. GitHub lets an
organization admin install your App directly from github.com, bypassing
orboto entirely - this button reconciles against GitHub's own
installation list, adding any installation orboto doesn't know about yet
and deactivating the connections for any installation that was removed on
GitHub's side. The result panel lists every installation it found, with
a "suspended" tag on any GitHub has itself suspended.

### GitLab - the guided manual flow [#gitlab---the-guided-manual-flow]

GitLab has no equivalent one-click App-creation flow, so this section
walks you through the manual steps instead of doing them for you:

1. **Open GitLab** - a button deep-links to GitLab's own
   application-settings page (your self-hosted instance's base URL if you
   set one in the field below, otherwise gitlab.com).
2. On that GitLab page, register a new OAuth application. Two copy
   buttons on the orboto page give you the exact values to paste:
   * **Redirect / Callback URL** - must match exactly, or GitLab's OAuth
     handshake will refuse orboto's callback.
   * **Scopes** - copy this exact string into GitLab's scopes field.
     Read-only connections need `read_api` + `read_repository`; branch
     creation from a ticket needs `api` + `write_repository`.
     Mark the application **Confidential** on GitLab's side - this is
     required for the OAuth flow to work as a server-side integration
     rather than a public client.
3. Back on orboto, paste GitLab's **Application ID** and **Application
   Secret** into the two fields at the bottom of this section, plus the
   **GitLab base URL** if you're on a self-hosted instance (leave empty
   for gitlab.com) and the **Redirect URI** if you need to override the
   default.
4. A **Disable GitLab OAuth flow** checkbox works the same way as the
   GitHub one - hides the card everywhere without discarding the saved
   credentials.

There's no "validate" button on the GitLab side; the first project that
connects through it will surface any credential problem immediately, at
which point re-checking the pasted Client ID/Secret against GitLab's
application page is the fix.

## Step 2 - connecting one project's repository [#step-2---connecting-one-projects-repository]

{/* screenshot: Project Settings - Git tab, "Add connection" three-card picker */}

Open the project you want to connect, go to **Settings -> Git -> Add
connection**. A three-option picker appears:

* **GitHub App** - shown as the recommended option (with a "recommended"
  tag) once a workspace App is configured; greyed out with an explanation
  if it isn't. Clicking **Continue to GitHub** takes you to GitHub's own
  installation screen. **Important**: on that screen, choose "Only select
  repositories" and pick just the ones this project actually needs -
  GitHub defaults to "All repositories", which orboto cannot narrow for
  you from its side; a small in-page note reminds you of this right
  before you leave for GitHub. Once you return, the repository is
  connected with no token to manage - GitHub issues short-lived
  installation tokens on demand instead of a long-lived secret sitting in
  orboto.
* **GitLab OAuth** - shown once a workspace OAuth app is configured;
  authorize once, orboto mints short-lived tokens automatically after
  that.
* **Manual token** - works for every provider: GitHub, GitLab, Azure
  DevOps / TFS, Bitbucket Cloud, Bitbucket Server, Gitea, Forgejo, or a
  read-only **SSH poll** connection. Picking a provider here shows a
  **Get a token** button that deep-links straight to the right
  token-creation page on that provider (GitHub's token-creation form
  pre-filled with the right scopes, GitLab's personal-access-token page,
  Azure DevOps's PAT settings for the org you type in, Bitbucket's App
  Passwords page, or the Forgejo/Gitea applications page on your
  self-hosted base URL). Self-hosted providers (GitLab self-managed,
  Azure DevOps, Bitbucket Server, Gitea, Forgejo) additionally need that
  instance's **base URL**; Azure DevOps also needs the org/project name
  since PATs there are org-scoped.

  The **SSH poll** option is different in kind from the rest: there is no
  token at all. orboto generates an ED25519 keypair itself when you save
  the connection and shows you the **public key** to add as a deploy key
  (or to your server's `authorized_keys`) on the repository's side. Use
  this for a self-hosted Git server that has no webhook support and no
  API to poll - orboto instead periodically checks the remote HEAD over
  SSH. It only supports read-only, poll-based updates (no branch
  creation, no webhook).

Every connection - regardless of provider or path - defaults to
**read-only**. Flip the read-only switch off, and supply a token with
write scope, if you want to let tickets create branches directly from
orboto. If the token you provide has webhook-admin scope on the
provider's side, orboto installs the inbound webhook automatically when
you save; otherwise the connection screen shows you the exact URL and
secret to paste into the provider's webhook settings by hand.

## How ticket linking actually works [#how-ticket-linking-actually-works]

Mention a ticket's key anywhere in a commit message or a pull-request
title - `ACME-42: fix the flux capacitor` - and that activity appears on
ticket ACME-42, tagged with its current state (open, merged, closed for a
PR; just "committed" for a plain commit). The activity feed on the ticket
is append-only for commits, but a pull request's entry **updates itself
in place** as the PR's state changes - you see one PR row that flips from
"open" to "merged", not a new row each time something changes on it.

## Connection health [#connection-health]

Each connection on the project's Git tab shows a health badge with two
independently-tracked signals, refreshed periodically in the background:

* **Outbound reachable** - can orboto currently reach the provider's API
  using the stored credentials.
* **Inbound delivering** - are webhook events actually arriving from the
  provider.

Hovering the badge shows both signals explicitly (a checkmark or cross
for each), the last time orboto probed, and - on failure - the specific
error orboto received. This is what makes a silently-broken integration
visible: a connection can look "fine" in the connection list while
quietly failing, and this badge is where that shows up first, before
someone notices commits aren't appearing.

## Troubleshooting [#troubleshooting]

* **Health badge shows outbound failing** - the token expired, was
  revoked, or lost scope on the provider's side. Regenerate it via the
  "Get a token" deep-link and update the connection; for a GitHub App
  connection specifically, re-register the App (Admin -> Git integration)
  or re-check its installation via **Sync installations**.
* **Health badge shows inbound not delivering** - the webhook was deleted
  or its secret rotated on the provider's side, outside orboto. If the
  token has webhook-admin scope, removing and re-adding the connection
  reinstalls the webhook automatically; otherwise re-paste the URL and
  secret manually into the provider's webhook settings.
* **Commits aren't appearing on a ticket even though the message looks
  right** - ticket-key matching is case-sensitive and must match the
  project's actual key exactly; also confirm the connection covers the
  exact repository the commit landed in, not a fork of it (a fork is a
  separate repository as far as the webhook is concerned).
* **A GitHub org installed the App directly from github.com and nothing
  shows up in orboto** - run **Sync installations from GitHub** (Admin ->
  Git integration, super-admin only) to pick it up.
* **The GitLab OAuth card is greyed out on a project's Add-connection
  screen** - the workspace-level Client ID / Secret haven't been set yet;
  a workspace admin configures them under Admin -> Git integration first,
  or you fall back to the Manual token path for GitLab in the meantime.
* **An SSH-poll connection never updates** - check the public key orboto
  generated was actually added as a deploy key (or to `authorized_keys`)
  on the target server, and that the server allows the SSH user/port you
  configured; there's no webhook to fall back on for this connection
  type, so a wrong key silently means "never polls successfully".


# Importing from other tools (/admin/data/import)



**Admin -> Import** brings an existing project into orboto through one
unified wizard: pick a source, configure it, choose a target project,
review and fix the mapping, then apply. It's the same wizard regardless
of which source you pick - only the configuration fields on step 2
change.

## Supported sources and how to reach them [#supported-sources-and-how-to-reach-them]

| Source             | Ways in                  | What you'll need                                                                                                                    |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Jira               | Cloud, live API          | Your Jira base URL, the account email, an API token, and the project key (case doesn't matter - orboto uppercases it automatically) |
| Jira               | An XML export file       | The exported XML file from Jira                                                                                                     |
| Notion             | Live API                 | A Notion internal-integration token; share the source database with the integration first                                           |
| ClickUp            | Live API                 | A ClickUp API token and the list to import                                                                                          |
| Monday.com         | Live API                 | A Monday API token (Admin → API, or your personal token) and the board                                                              |
| Linear             | Live API                 | A Linear API key and the team key (e.g. `ENG`)                                                                                      |
| Linear             | A JSON export file       | The exported JSON file                                                                                                              |
| GitHub Issues      | Live API                 | A token, the repository owner, and the repository name                                                                              |
| GitHub Issues      | A JSON export file       | The exported JSON file                                                                                                              |
| GitLab Issues      | Live API                 | A personal access token and the project path                                                                                        |
| Asana              | Live API                 | An Asana API token                                                                                                                  |
| Asana              | A JSON export file       | The exported JSON file                                                                                                              |
| Trello             | Live API                 | A Trello API key + token                                                                                                            |
| Trello             | A board JSON export file | The exported board JSON                                                                                                             |
| Azure DevOps / TFS | Live API                 | The org/collection base URL (cloud or on-prem), the project name, and a Personal Access Token with Work Items: Read                 |
| Redmine            | Live API                 | Your Redmine base URL and an API key                                                                                                |
| CSV                | Any spreadsheet export   | A `.csv` file - column headers can be anything, you bind them manually in step 4                                                    |

Where both a live-API and an export-file path exist for the same source,
the live-API path pulls richer data (attachments, full comment threads,
live user directory for better matching) than a static export - prefer it
whenever you can mint the credentials. The export path exists for when
you can't get API access (a decommissioned instance, a source system your
new employer won't grant you a fresh token for) or the source no longer
exists at all and only a downloaded archive survives.

## The five-step wizard [#the-five-step-wizard]

### Step 1 - pick the source [#step-1---pick-the-source]

A grid of cards, one per adapter. Click one to move to configuration.

### Step 2 - configure [#step-2---configure]

The form here is generated from the chosen adapter's own field
definitions, so it only ever asks for what that specific source needs
(see the table above). A few things apply across every adapter:

* **Secret-looking fields** (API tokens, passwords) render as password
  inputs so the value isn't visible on screen by default.
* Whatever you type is cached **on this device only** - non-secret
  fields in local storage, tokens in session storage (cleared when you
  close the tab) - so re-importing from the same source later pre-fills
  the form. **Clear saved config** wipes this cache if you're on a shared
  machine or switching accounts.
* A file-upload adapter (an export-based one, or CSV) shows a file picker
  instead of text fields; the file uploads and stages itself before you
  can continue, with a progress indicator and, once done, the filename
  and size shown back to you.
* A link to that provider's own documentation for generating the
  credential you need sits right above the form, so you don't have to
  leave and hunt for it separately.

You can't continue until every required field is filled; optional fields
are marked as such.

### Step 3 - pick the target [#step-3---pick-the-target]

Two choices, as radio options:

* **Create a new project** - orboto names it after the source by
  default; you can rename it afterward. Optionally set the **project
  key** yourself here (2-10 uppercase letters/digits) - leave it empty
  and orboto derives one from the source name.
* **Merge into an existing project** - pick from a searchable list of
  your existing projects. Imported tickets keep their original source
  IDs even when merging, and labels/milestones are matched to the
  target project's existing ones **by name** (see step 4's mapping
  tables for how to control this).

Click **Preview import** to move on - this is where orboto actually talks
to the source (or parses the uploaded file) for the first time.

### Step 4 - preview and fix the mapping [#step-4---preview-and-fix-the-mapping]

{/* screenshot: Admin - Import wizard, preview step with a mapping table */}

You land here with a **source summary** (counts: users, milestones,
labels, tickets, comments, time entries, dependencies) and any
**warnings** orboto already noticed (e.g. a field it couldn't map
automatically). Below that, a mapping table per entity type - only the
tables relevant to what the source actually contains appear:

* **Users** - one row per distinct source user. For each, pick from a
  dropdown: an existing orboto account (matched by email where possible,
  including previously-deactivated accounts from an earlier import so a
  re-import can land on the same person instead of forking a duplicate),
  **Create placeholder user** (no sign-in ability, but every ticket and
  comment they authored keeps correct attribution), or **Skip this
  user** (drops anything they were assigned, and their comments get
  re-attributed to you, the person running the import).
* **Ticket statuses** - one row per distinct status value found in the
  source. Map each to one of the target project's real statuses, or
  leave it on the default ("project's first To Do status") if you don't
  care about preserving the exact workflow state on import.
* **Labels** - one row per distinct label. **Create from source name**
  (default) or match it to an existing label in the target project.
* **Milestones** - same pattern as labels: create from source name, or
  match to an existing milestone.

**CSV only** gets an extra screen before this one: **column binding**.
orboto shows every column header it found in your file and asks you to
pick which column feeds which orboto field (title, description, status,
priority, type, assignee email, labels, milestone, due date, source key).
Title is the only required binding; leave the rest unbound to skip that
field entirely for every row.

Fix whatever the mapping table doesn't already get right, then click
**Apply import**.

### Step 5 - apply and review the result [#step-5---apply-and-review-the-result]

Small imports apply immediately. Larger ones run as a background job
instead, with a live progress bar (tickets applied / total) so the
browser tab never has to stay open and blocked on a long-running request.
When it finishes you get:

* A **created** count broken down by entity type.
* Any **warnings** collected along the way.
* For a background-job import specifically, a **reconciliation** line:
  how many of the staged rows actually landed vs. how many are
  unaccounted for. If any are missing, the specific source rows and the
  reason each one failed are listed so you can fix the underlying
  problem (a bad attachment reference, a field that didn't validate) and
  decide whether to re-run just that portion.
* A direct **Open project** link into the freshly imported (or
  topped-up) project.

Imports are **transactional per project** - if the apply step fails
partway through, it does not leave a half-imported project behind; you
get a clean failure to fix and retry, not a mess to clean up by hand.

## Notes [#notes]

* Imported tickets keep their original source identifier in the
  description or metadata, so an old link (a Jira issue key, a GitHub
  issue number someone bookmarked) stays traceable back to where it came
  from.
* AI features (semantic search, duplicate detection) index imported
  content automatically once the import completes - there's no separate
  "reindex after import" step to remember.
* Re-running an import creates **new** items every time - it does not
  detect or skip anything it already imported in a previous run.
  Deduplicate at the source before re-importing the same data twice, or
  merge deliberately into the same target project and accept the
  duplicates if that's actually what you want.
* Imports write content in the workspace's expected language (Admin ->
  System settings -> Workspace language). Content that arrives in a
  different language still imports successfully, but degrades search and
  AI features for that content - watch for a repeated language-mismatch
  warning across a batch as a sign the batch itself may be the wrong
  language for this workspace, not a bug in the import.

## Troubleshooting [#troubleshooting]

* **The configure step rejects your credentials before you even get to
  preview** - double-check the base URL for any self-hosted source (Jira
  Server/Data Center, GitLab self-managed, Redmine, Azure DevOps Server
  all need their OWN instance URL, never the vendor's cloud default), and
  confirm the token actually has read access to the specific
  project/team you named, not just to your account in general.
* **CSV preview shows zero tickets** - the column-binding step hasn't run
  yet, or the Title column specifically wasn't bound to anything. Go back
  one step and bind it - it's the only required column.
* **A user keeps showing "create placeholder" even though they clearly
  already have an orboto account** - the source's email for them doesn't
  exactly match the existing account's email (a common cause: they
  changed email addresses since the source system was set up). Pick them
  manually from the mapping dropdown instead of relying on the automatic
  email match.
* **Unmapped statuses all collapsed onto "To Do"** - that's the
  documented fallback for anything left unmapped in the Statuses table;
  go back and map them explicitly before applying if preserving the
  exact workflow state matters, since it's far easier to fix here than
  to bulk-move tickets after the fact.
* **The result screen shows tickets "unaccounted for"** - only happens on
  the background-job path; it means the reconciliation pass found staged
  rows that neither landed as tickets nor were recorded as failures. Read
  the listed reasons for the specific rows, fix the underlying issue, and
  re-run just that source data if it's worth the effort - otherwise treat
  it as a small number of rows to recreate by hand.


# Webhooks (/admin/data/webhooks)



Webhooks POST an event payload to your endpoint whenever something
happens in the workspace - a ticket created or changed, a comment posted,
and more. They're the integration point for anything orboto doesn't
already connect to natively.

## Workspace vs. project scope [#workspace-vs-project-scope]

Webhooks exist at two levels, managed on two different pages, and you
choose the scope by which page you create one on:

* **Admin -> Webhooks** - a workspace-scoped webhook fires for the event
  types you picked, across every project in the workspace. Use this for
  a system that needs to know about everything (a company-wide Slack
  channel, a central logging pipeline).
* **Project Settings -> Webhooks** (inside a specific project) - fires
  only for that one project. Use this when only one team or one
  integration cares about a specific project's activity.

Both pages have the identical setup form and delivery log described
below - only what triggers the webhook differs.

## Setting one up [#setting-one-up]

{/* screenshot: Admin - Webhooks page, "New webhook" form with the template picker */}

Click **New**. The form asks for:

1. **A template** (optional first step) - four cards: **Generic** (a
   plain JSON envelope you consume however you like), **Slack**,
   **Microsoft Teams**, or **Discord**. Picking a vendor template
   pre-fills the payload **format**, a placeholder for that vendor's
   webhook URL shape, and a sensible starter set of subscribed events -
   all still fully editable afterward. Picking **Generic** (or skipping
   this step) leaves the payload as the plain JSON envelope.
2. **Name** - your own label for this webhook, shown in the list.
3. **URL** - your receiving endpoint.
4. **Events** - a checklist of every event this webhook can fire for
   (see the table below). Check only what you actually need; the fewer
   events, the smaller the log and the less noise on your receiver.
5. Optionally expand **Show example** to see exactly what JSON body the
   currently-selected template produces, before you save anything.

Click **Save**. A banner appears **once**, immediately after creation,
showing the webhook's **secret** in plaintext - copy it now. orboto never
displays it again; if you lose it, delete the webhook and create a new
one rather than trying to recover the old secret.

## Events you can subscribe to [#events-you-can-subscribe-to]

| Event                                       | Fires when                                                                                                          |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `ticket.created`                            | A new ticket is created                                                                                             |
| `ticket.updated`                            | Any field on an existing ticket changes                                                                             |
| `ticket.deleted`                            | A ticket is deleted                                                                                                 |
| `comment.created` / `.updated` / `.deleted` | A comment is posted, edited, or removed                                                                             |
| `project.member_added` / `.member_removed`  | Someone joins or leaves a project                                                                                   |
| `milestone.created` / `.updated`            | A milestone is created or changed                                                                                   |
| `version.released`                          | A project version is marked released                                                                                |
| `ticket.checklist_item.completed`           | A checklist item flips from unchecked to checked (fires once, on that transition only - not on every edit)          |
| `inbound.signal.received`                   | An inbound-mail message was triaged but didn't match any ticket, so it was forwarded as a standalone signal instead |

The **Event reference** panel at the bottom of the Webhooks page lists
every event orboto can dispatch, each in its own collapsible row showing
the description and the *exact* JSON payload your receiver will get for
it, inside the standard envelope `{ event, data, timestamp }`. Expand a
row and use its **Copy** button to grab a ready-to-use example straight
into a test script or a Postman request - you never have to guess a
payload's shape from the checkbox label alone.

## Verifying deliveries [#verifying-deliveries]

Every request carries the header:

```
X-Orboto-Signature: sha256=<hmac-sha256 of the raw body, keyed with your secret>
```

Verify it before trusting the payload:

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
```

Reject anything unsigned or mismatched - don't process a payload just
because it arrived at the right URL.

## Delivery behavior and the delivery log [#delivery-behavior-and-the-delivery-log]

* Dispatch is asynchronous and fire-and-forget: whatever mutation
  triggered the event (creating a ticket, posting a comment) completes
  and returns to the user immediately, regardless of whether your
  endpoint is fast, slow, or entirely down at that moment.
* Every attempt - success or failure - lands in that webhook's
  **delivery log**, viewable from the webhook's row in the list. Each
  entry shows the event, the timestamp, the HTTP status your endpoint
  returned (or a timeout/connection error), and, for a failure, the
  response body or error detail. There's no guesswork required to debug
  a silent integration - the log tells you exactly what happened on the
  last N attempts.
* **Disable** (rather than delete) on a webhook stops new deliveries
  immediately while keeping its configuration, secret, and full delivery
  history intact - use this while you're fixing a broken receiver, then
  **Enable** it again once it's ready.
* Deleting a webhook removes it and its delivery history permanently.

## Troubleshooting [#troubleshooting]

* **Signature never matches on your receiver** - HMAC the *raw* request
  body bytes exactly as received, before any JSON parsing/re-serialization.
  Re-stringifying a parsed body (different key order, different
  whitespace) produces a different hash than the one orboto signed.
* **Nothing arrives at all** - open the delivery log first. Zero attempts
  logged means the event you expected isn't among the ones you checked
  when creating the webhook (or nothing matching has happened yet, in
  which case trigger a test action - create a ticket - to confirm).
  Attempts logged as failures mean your endpoint rejected the request or
  timed out; the log's status code and error detail say exactly why.
* **A vendor template's payload doesn't render correctly in Slack /
  Teams / Discord** - each vendor template targets that platform's own
  message format (Slack blocks, Teams adaptive cards, Discord embeds
  respectively). If you've customized the receiving channel or app
  beyond what the default template assumes, switch to **Generic** and
  transform the payload yourself downstream instead of fighting the
  built-in template.
* **You lost the signing secret** - it's shown exactly once, at creation.
  There's no recovery flow; delete the webhook and recreate it, which
  issues a fresh secret you copy immediately this time.
* **Wrong scope: getting events from projects you didn't expect** - a
  workspace-level webhook (Admin -> Webhooks) fires for every project by
  design; if you only want one project's events, delete it there and
  create the equivalent webhook on that project's own Settings ->
  Webhooks page instead.


# Email templates (/admin/email/email-templates)



Every outbound email - invitations, notifications, digests, alerts - is
rendered from an editable template. **Admin → Email templates** lists
them all, grouped (Auth & onboarding, Notifications, Digest, Alerts,
System, Custom) with a status badge: **Default**, **Customised**, or
**Disabled**. Search by subject or template key.

{/* screenshot: the email templates list grouped by category with status badges */}

This is a Business/Enterprise feature. On the Community plan editing
still works but raises a soft-warn on the License page; nothing is
blocked.

## Branding [#branding]

The **Branding** section at the top of the list applies workspace-wide,
across every template: logo URL, footer text, primary colour, link
colour, and separate heading/body fonts. Changing it here propagates
everywhere immediately - you don't edit colours per template.

{/* screenshot: the branding form with logo URL, colour pickers and font selects */}

## The master layout [#the-master-layout]

A shared **master template** provides the frame every other email
renders into (header, footer, branding) - one branding change applies
everywhere. It's edited like any other row from its own card above the
grouped list, but as a raw HTML source instead of the rich editor: the
master layout is a full document (doctype, tables, inline styles, a logo
`<img>`) that the rich editor would strip down to a plain fragment, so it
gets a plain-text HTML box instead. A template can opt out of the master
frame for a bare email where that's more appropriate.

## Editing a template [#editing-a-template]

Open a row to reach the editor: subject field, body editor, and a live
preview side by side.

{/* screenshot: the template editor with the body editor on the left and the live preview on the right */}

* **Subject** - plain text with `{{variable}}` placeholders; a picker
  shows the variables available for this template.
* **Body** - a rich, email-safe editor (Tiptap). Reference a variable
  with `{{name}}` for HTML-escaped substitution, or `{{{name}}}` to
  splice raw HTML - avoid the triple-brace form unless you trust the
  source.
* **Plain-text override** (optional) - leave empty and orboto
  auto-generates the plain-text version from the HTML at render time;
  paste your own if you want an opinionated version for accessibility
  tools or plain-text mail clients.
* **Preview** - renders live as you type (debounced), with desktop and
  mobile widths and HTML / plain-text tabs.

**Send test to me** sends a rendered copy - using sample data from the
variable catalog - to your own email address via the workspace's
configured email provider, so you can check real client rendering before
committing.

### Disabling a template [#disabling-a-template]

The **Email enabled** switch at the bottom of the editor is a kill
switch: turning it off stops orboto from sending that email type
entirely, while in-app notifications (where the same event also has one)
keep working. Useful for muting a noisy notification type without
touching the underlying feature.

### Reset to default [#reset-to-default]

**Reset to default** restores the shipped subject and body, discarding
your edits (confirm dialog). Your customization is tracked separately
from the built-in version, so product updates never silently overwrite an
edit you kept.

### History [#history]

**History** opens every prior saved version of this template (subject +
body), each save recorded automatically - restore an earlier version if
a reset went too far or an edit needs undoing.

{/* screenshot: the History modal listing prior revisions with a Restore action */}

### System-managed templates [#system-managed-templates]

A few templates (storage-quota warnings and similar) are locked - shown
with a lock icon, no edit link. Their body is owned by the system so the
alert UX stays consistent; configure their thresholds and recipients from
the relevant Alerts & Notifications settings instead.

## Languages [#languages]

Templates are edited in the **workspace's default locale** only - there
is no per-locale picker. A recipient in any other language gets the
built-in default for their locale automatically. To get your
customization into other languages, use **Auto-translate locales** on an
already-customized template: it machine-translates your edited subject
and body into every other seeded locale via the workspace's AI provider,
marking each as customized. Re-running it **overwrites** any existing
customized translation for those locales - it's meant for "I edited the
English version, now sync everything else," not for hand-tuning
individual languages afterwards. The button only appears once AI is
configured and the template has at least one customization to translate
from.

## Troubleshooting [#troubleshooting]

**Auto-translate button is missing.** It only shows once the template is
customized (nothing to translate from the shipped default) and once the
workspace has an AI provider configured under Admin → AI.

**Edited the template but the email still looks like the old version.**
Check you saved on the workspace's default locale - the editor has no
locale picker, so if you're expecting a non-default-locale recipient to
see your edit, run auto-translate after saving, or confirm that locale
hasn't been separately customized to something else via a translation.

**Save button is disabled.** It's a system-managed template (locked, no
edit access here) - configure it via the relevant Alerts & Notifications
settings instead. Otherwise, Save only enables once you've actually
changed the subject or body.

**A template stopped sending.** Check its status badge for **Disabled** -
the "Email enabled" switch in its editor may have been turned off.


# Inbound email (/admin/email/inbound-email)



Four ways to land email in orboto as tickets. Pick the one that matches
your deployment constraints.

## Which path do I want? [#which-path-do-i-want]

| Path                                                          | Latency     | DNS work             | Port 25 needed | Best for                                                                                                                                                                               |
| ------------------------------------------------------------- | ----------- | -------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider webhook** (UseSend / Resend / Postmark / SendGrid) | seconds     | none                 | no             | Easiest setup, managed spam handling, needs a third-party email-receive account. UseSend is the EU / DSGVO-clean pick (open-source, self-hostable, AWS SES `eu-central-1` underneath). |
| **IMAP polling**                                              | up to 5 min | none                 | no             | You already have a mailbox you want orboto to read                                                                                                                                     |
| **Self-hosted SMTP**                                          | seconds     | MX + A + SPF + DMARC | yes            | Per-project addresses, no third party in the loop                                                                                                                                      |
| **Cloudflare Email Routing → webhook**                        | seconds     | MX (Cloudflare)      | no             | Self-hosted SMTP isn't viable (port 25 blocked) but you still want Cloudflare to receive mail at your domain                                                                           |

All four paths share the same back-end: every message runs the
auth-policy gate, the sender allowlist, the known-user check, the
project-routing chain (per-project address → `tickets+KEY@host` regex →
semantic embedding vote → catchall → default), AI cleanup, and ticket
creation. The only difference between paths is how the message reaches
that pipeline.

## Provider webhook [#provider-webhook]

**Admin → Inbound mail** shows a cheat sheet with the webhook URL and the
bearer-secret header to paste into your provider's inbound-webhook config

* generate the secret there first, then wire up Resend / Postmark /
  SendGrid / UseSend to POST to that URL. The same page holds the sender
  allowlist, the "require known orboto user" toggle, the SPF/DKIM/DMARC
  authentication policy, and the default fallback project.

{/* screenshot: the Admin → Inbound mail cheat sheet with webhook URL and bearer secret */}

## Self-hosted SMTP [#self-hosted-smtp]

Bind orboto's built-in SMTP server to port 25 (or any port) and let
external MTAs deliver mail directly.

### VPS / host requirements [#vps--host-requirements]

* **Port 25 must be open outbound AND inbound.** AWS, GCP, and
  DigitalOcean block port 25 by default and require a support ticket
  to lift. Hetzner, OVH, Vultr, and most bare-metal hosts allow it.
* A static public IPv4 address (or IPv6 with proper PTR).
* A DNS zone you control for the email domain.

### Configure orboto [#configure-orboto]

`Admin → Inbound SMTP`:

* **Hostname**: `mail.example.com` - what orboto announces in the SMTP
  banner and what your MX record will point to.
* **Listen host / port**: `0.0.0.0` / `25` for production. `127.0.0.1`
  * a high port works for local testing.
* **TLS mode**:
  * `proxy` - Caddy or Traefik terminates TLS in front; orboto speaks
    plaintext on the bound port. Cleanest for Coolify deploys.
  * `in_process` - orboto terminates TLS itself. Provide cert + key
    paths; you own renewal.
  * `off` - no STARTTLS. Only for trusted private networks.
* **Catchall project** - fallback project when no per-project address
  matches and no `tickets+KEY` alias is present. Leave empty to hard-
  reject unknown recipients with `550`.
* **Rate limit** - per-IP requests per 5 minutes. Default 20 is
  generous for legitimate MTAs, low enough to throttle abuse.

{/* screenshot: the Admin → Inbound SMTP config page with the DNS checklist */}

Saving restarts the listener in-process - no redeploy needed.

### DNS records [#dns-records]

Replace `mail.example.com` and `203.0.113.10` with the real host /
IP. The DNS checklist in the admin UI surfaces these with copy-to-
clipboard buttons.

```
; A record - pin the SMTP hostname to the IP
mail.example.com.  IN  A     203.0.113.10

; MX record - tell senders to deliver mail for example.com here
example.com.       IN  MX    10  mail.example.com.

; SPF - authorise the host to send for the domain (matters when you
; later send notifications from the same hostname)
example.com.       IN  TXT   "v=spf1 ip4:203.0.113.10 -all"

; DMARC - enable reporting + authentication policy
_dmarc.example.com. IN TXT   "v=DMARC1; p=quarantine; rua=mailto:postmaster@example.com"
```

### Reverse DNS (PTR) [#reverse-dns-ptr]

Most major receivers (Gmail, Outlook, Yahoo) reject mail from hosts
without a PTR record. Set `203.0.113.10 → mail.example.com` via your
hoster's control panel. Without this, your outbound notifications
will likely land in spam.

### Reverse proxy (TLS mode = `proxy`) [#reverse-proxy-tls-mode--proxy]

Add a stream block to Caddy or Traefik so external connections to port 25
reach the orboto container's bound port internally - see the
reverse-proxy examples in the [self-hosting guide](/self-hosting/docker).

### Per-project addresses [#per-project-addresses]

Once SMTP is enabled workspace-wide, a new **Inbound Email** tab
appears in Project Settings. Project admins register addresses like
`support@mail.example.com` (the local-part plus the SMTP hostname). Mail
to that address routes to that project as a new ticket.

The `tickets+KEY@mail.example.com` alias is always accepted in addition:
it routes by project key (`tickets+ACME@mail.example.com` posts to
project `ACME`).

### Testing [#testing]

```bash
# swaks (apt install swaks) - full SMTP transaction.
swaks --to support@mail.example.com --from you@gmail.com \
      --header "Subject: Hello from swaks" --body "Test body"

# Confirm the MX record resolves
dig mx example.com +short
# Confirm the host accepts on port 25
nc -zv mail.example.com 25
```

## Cloudflare Email Routing → webhook [#cloudflare-email-routing--webhook]

Free workaround when port 25 is blocked. Cloudflare receives mail at
your domain and forwards it to a Worker that POSTs to orboto's
`/inbound-mail` webhook.

### Cloudflare setup [#cloudflare-setup]

1. Cloudflare dashboard → your domain → **Email → Email Routing**.
   Click **Get started** and verify the destination address (your
   personal inbox - required even though it isn't used for anything).
2. Email Routing automatically writes the MX records into your zone.
3. Add a **catch-all rule** that runs an Email Worker.

### Email Worker [#email-worker]

In Cloudflare dashboard → **Workers & Pages → Create → Email
Worker**, paste:

```js
export default {
  async email(message, env) {
    const raw = await new Response(message.raw).text();

    // Pull a few headers we need before re-encoding the body.
    const headers = [];
    for (const [name, value] of message.headers.entries()) {
      headers.push({ name, value });
    }

    const payload = {
      from: message.from,
      to: [message.to],
      subject: message.headers.get('subject') ?? '',
      text: raw,                        // raw MIME - the ingest service parses it
      html: null,
      headers,
    };

    const res = await fetch(`${env.ORBOTO_URL}/inbound-mail`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${env.ORBOTO_INBOUND_SECRET}`,
      },
      body: JSON.stringify(payload),
    });

    if (!res.ok) {
      const body = await res.text();
      // Bouncing back to sender is rude in this flow - Cloudflare
      // already accepted the mail. Log + drop instead.
      console.error('orboto forward failed', res.status, body);
    }
  },
};
```

Set the Worker's environment variables:

* `ORBOTO_URL` = `https://orboto.example.com`
* `ORBOTO_INBOUND_SECRET` = the bearer secret shown under
  `Admin → Inbound mail`.

### Pros / cons vs self-hosted SMTP [#pros--cons-vs-self-hosted-smtp]

|                  | Cloudflare → webhook                   | Self-hosted SMTP          |
| ---------------- | -------------------------------------- | ------------------------- |
| Latency          | seconds                                | seconds                   |
| Spam filtering   | Cloudflare's                           | orboto's gates only       |
| DKIM / SPF check | Cloudflare passes verdicts via headers | orboto checks them itself |
| Cost             | free                                   | VPS + monitoring          |
| Port 25 needed   | no                                     | yes                       |

## IMAP polling [#imap-polling]

Best when you already have a mailbox (a Gmail group, an M365 shared
inbox) and don't want to change DNS or run an SMTP server.

### Add an account [#add-an-account]

`Admin → Inbound IMAP → New account`:

* **Label** - operator-facing name only.
* **Host / port / TLS** - `imap.gmail.com` / `993` / on for Gmail
  and most providers.
* **Username** - full email address.
* **Password** - see provider-specific section below.
* **Folder** - `INBOX` is the default; use `Inbox/orboto` to
  partition.
* **Poll interval** - default 5 minutes. Lower to 1 minute on hosts
  that allow it; some providers throttle aggressive polling.
* **Use IMAP IDLE** - push notifications instead of polling. Falls
  back to polling on failure.

{/* screenshot: the Admin → Inbound IMAP account form with Test connection and Poll now buttons */}

**Test connection** connects, selects the folder, and returns the message
count. **Poll now** runs the same fetch logic the cron uses - useful to
verify a fix without waiting for the next interval.

### Gmail / Google Workspace [#gmail--google-workspace]

Gmail no longer accepts plain account passwords for IMAP; you need
an **App Password**:

1. Google account → **Security → 2-Step Verification** (must be on).
2. **App passwords**, generate one for "Mail".
3. Use that 16-character password in orboto.

### Outlook / Microsoft 365 [#outlook--microsoft-365]

Microsoft is migrating off basic IMAP auth. For now:

1. **Account → Security → Advanced security options → App passwords**
   (only available when 2FA is on).
2. Use the generated app password.

### Generic IMAP [#generic-imap]

Whatever your provider's IMAP settings page says. Standard ports: `143`
STARTTLS, `993` implicit TLS (recommended). Passwords are
AES-256-GCM-encrypted at rest and never written or returned in plaintext.

## Troubleshooting [#troubleshooting]

### "Email not received" [#email-not-received]

Open `Admin → Inbound log` first - every accepted, rejected, or duplicate
message lands there with the reason.

{/* screenshot: the inbound log with an accepted row and a rejected row showing the rejection chip */}

* **No row at all** - the message never reached the ingest pipeline. For
  SMTP: check the listener is running (admin SMTP page + `/ready`). For
  webhook: confirm the bearer secret is set and the provider isn't
  throwing 401s on its side. For IMAP: the account row's `last_error`
  column carries the most recent fetcher error.
* **Accepted, but the ticket isn't where you expect** - check the project
  routing chain. The log row links to the ticket; click through.
* **Rejected** - the reason appears as a chip:
  * `auth_policy_failed` - the SPF/DKIM/DMARC gate. Check the
    authentication policy and the inbound headers (see below).
  * `sender_domain_not_allowed` - the sender's domain isn't on the
    allowlist. Add it, or clear the allowlist to accept any domain.
  * `sender_not_known` - "require known user" is on and the sender's
    email isn't an orboto user.
  * `no_project_routing` - none of the routing steps matched. Add a
    per-project address, set a catchall, or set a default project.
  * `duplicate` - the same Message-ID was already processed. Replies in
    an existing thread route via the In-Reply-To map, not the dedup
    index.

For SMTP specifically, also check your hoster hasn't quietly blocked port
25 (`telnet your-host 25` from outside).

### Reading Authentication-Results headers [#reading-authentication-results-headers]

The header line looks like:

```
Authentication-Results: example.com;
  spf=pass smtp.mailfrom=sender@gmail.com;
  dkim=pass header.d=gmail.com;
  dmarc=pass action=none header.from=gmail.com
```

Each mechanism reports `pass` / `fail` / `none`. orboto's policies:

* `off` - no enforcement.
* `permissive` - `dmarc=pass` required.
* `strict` - `spf=pass` AND `dmarc=pass` required.

DKIM is informational; orboto does not gate on DKIM alone.

### Outbound deliverability [#outbound-deliverability]

Notifications landing in spam is a SEND problem, not a receive problem -
see your provider's (UseSend / Resend / SMTP) sending configuration, set
up SPF + DKIM for the sending domain, and consider warming a fresh IP.


# Decision records (/admin/governance/decision-records)



## What a decision record is [#what-a-decision-record-is]

A **decision record** (the pattern is widely known as an
"Architecture Decision Record" or ADR, though orboto's version isn't
limited to architecture) is a short, structured document capturing one
significant decision: what situation prompted it, what options were on
the table, which one was chosen, and why. The point isn't ceremony for
its own sake - it's that six months from now, someone (possibly you)
will ask "why did we do it this way instead of the obvious alternative,"
and the honest answer will either be sitting in a searchable record, or
it will be gone, guessed at, or worse, contradicted by someone's
half-remembered version of events.

orboto's decision records add two things a plain wiki page usually
lacks: a **workflow status** so a decision's lifecycle is explicit
(proposed, not just "written down somewhere"), and an **append-only
sign-off trail** so you can prove specific people actually reviewed and
approved it, not just that someone typed up a rationale after the fact.

## Fields, explained [#fields-explained]

* **Title** - a short, specific name for the decision (e.g. "Use
  PostgreSQL over MongoDB for the ACME billing service").
* **Context** - the situation or problem that made a decision necessary
  in the first place. Write this as if the reader has none of the
  background you currently have - because eventually, they won't.
* **Options considered** - the alternatives that were actually on the
  table, one per line. Listing the roads not taken is often more useful
  later than the choice itself: it proves the decision wasn't made in a
  vacuum, and it saves a future team from re-litigating an option that
  was already ruled out for a documented reason.
* **Chosen option** - which of the above was picked.
* **Rationale** - *why* that option won. This is the field that answers
  the "why" question a year from now.
* **Consequences** (optional) - the known trade-offs or follow-on
  effects of the choice, if you know them up front.
* **Status** - proposed / accepted / rejected / superseded / deprecated
  (see below).
* **Accountable owner** - the person responsible for the decision.
* **Linked project / milestone / ticket** (optional) - ties the record
  to the concrete work it relates to, so it shows up in context rather
  than only in a standalone log.

## Recording a decision [#recording-a-decision]

1. Open **Admin -> Governance** and use the **Decision log** card.
2. Fill in the title, context, options considered (one per line), the
   chosen option, and the rationale. Consequences are optional but worth
   filling in when you already know them.
3. Optionally set an **accountable owner** and link a project, milestone,
   or ticket.
4. Click **Record decision**.

{/* screenshot: Admin - Governance page, Decision log card with the create form filled in */}

## Sign-offs [#sign-offs]

A decision can carry a **sign-off trail**: a record of who reviewed it
and their verdict. Two ways this happens:

* **Request sign-off** - pick one or more approvers and an optional
  message; each named approver is notified.
* **Approve / Reject** - anyone reviewing the decision can add their own
  verdict directly, with an optional comment, whether or not they were
  formally requested.

Every sign-off is **append-only** - a rejected verdict doesn't get
edited into an approval later; if someone changes their mind, that's a
new sign-off entry, so the trail always shows the full history of who
said what and when, not just the latest state.

{/* screenshot: Admin - Governance page, a decision's sign-off trail with mixed approve/reject verdicts */}

## Status and superseding [#status-and-superseding]

A decision's status tracks its lifecycle:

| Status     | Meaning                                            |
| ---------- | -------------------------------------------------- |
| Proposed   | Written up, not yet formally accepted              |
| Accepted   | The decision stands and is in effect               |
| Rejected   | Considered and explicitly not adopted              |
| Superseded | A later decision has replaced this one             |
| Deprecated | No longer relevant, without a specific replacement |

Decisions change over time - that's expected, not a failure of the
original one. Instead of editing an old decision to reflect new
thinking (which destroys the very history you were trying to preserve),
**record a new decision and mark it as superseding the old one**. The
old record automatically flips to **superseded** status and gains a
visible link forward to the decision that replaced it, while the new
record links back. Both stay readable - you get the full "we decided X,
then later decided Y instead, and here's why" chain, rather than a
single record that's been silently rewritten.

## Exporting for evidence [#exporting-for-evidence]

Click **Export** on the Decision log card to download every decision
record - full detail, including sign-off trails - as a machine-readable
file. This is built specifically for handing to an auditor or attaching
to a customer's security questionnaire response, so you don't have to
reconstruct a decision history from scratch every time someone asks for
it.

## Permissions [#permissions]

Reading decisions requires `admin:decision:read`; creating, updating,
recording a sign-off, requesting one, and deleting all require
`admin:decision:write`. Every mutation - including each individual
sign-off verdict - is written to the audit log, because for this
surface the trail itself is the point.

## Troubleshooting [#troubleshooting]

* **I need to change a decision I already recorded** - if the facts
  described are simply wrong (a typo, a missing detail), edit it
  directly. If the *decision itself* has genuinely changed, don't edit
  the old record - record a new one and mark it as superseding the old
  one, so the history of "we used to think X, now we think Y" survives.
* **A sign-off I requested never got a response** - sign-off requests
  notify the named approvers but don't enforce a deadline; follow up
  with them directly, or request sign-off again if the original
  notification may have been missed.
* **I can't find an old decision anymore** - check whether it was marked
  superseded or deprecated; by default the list may be scoped to active
  decisions, so switch to viewing all statuses (including superseded) to
  see the full history.
* **The Export button doesn't include something I expected** - export
  covers every decision record and its full sign-off trail regardless of
  status, so if something's missing, confirm it was actually recorded
  as a decision record here rather than tracked elsewhere (a ticket
  comment, a doc page) that this feature doesn't scan.


# Governance overview (/admin/governance)



**Admin -> Governance** is a set of tools for teams that need to prove -
not just do - disciplined risk management and decision-making: think
ISO 27001 audits, SOC 2 evidence requests, enterprise customer security
questionnaires, or simply a growing team that wants "why did we decide
this" to stop living in someone's memory or a Slack thread that
scrolled away. It's an **Enterprise** feature; see the note at the
bottom of this page for how it behaves on other editions.

## Who this is for [#who-this-is-for]

If you've never needed to answer "show me your risk register" or
"who signed off on that architecture change" from an auditor, customer
security team, or your own leadership, this toolset will feel like
overhead you don't need yet - and that's a fair read for a small team
moving fast. It earns its keep once any of the following starts being
true: you're pursuing a compliance certification, a customer's security
review asks for evidence of a formal decision process, you've been
burned by a risk nobody tracked until it became an incident, or your
team has grown past the point where "everyone just remembers why we did
that" still holds.

## The three pieces [#the-three-pieces]

Governance splits into three focused surfaces, each documented in its
own guide:

* **[Decision records](/admin/governance/decision-records)** - a
  structured, ADR-style log of significant decisions: the situation, the
  options considered, what was chosen and why, an accountable owner, and
  an append-only sign-off trail. Answers "why did we do it this way" for
  anyone asking six months later.
* **[Risk register](/admin/governance/risk-register)** - risks
  tracked as first-class records with a likelihood x impact matrix, a
  mitigation owner and plan, a workflow status, and a recurring review
  cadence that reminds you before a risk goes stale. Answers "what could
  go wrong, and who's watching it."
* **[On-call and escalations](/admin/governance/on-call-and-escalations)**
  * who's on duty right now, and the tiered chain that makes sure an
    unacknowledged alert or SLA breach eventually reaches an actual human
    rather than sitting unnoticed. Answers "if something goes wrong at
    3am, who finds out."

A fourth card on the same admin page, the **compliance control
catalog**, lets you catalog controls from a framework you're attesting
to (for example ISO 27001 Annex A) with an owner and a recurring
**attestation cadence** - each attestation is an append-only
acknowledgement written to the audit trail, the same evidentiary pattern
as decision sign-offs. It doesn't have its own guide yet; the card's
own in-app description covers its fields, and it follows the same
audit-trail philosophy as the pages above.

{/* screenshot: Admin - Governance page showing all cards */}

## The common thread: the trail is the deliverable [#the-common-thread-the-trail-is-the-deliverable]

Every mutation across this toolset - creating a risk, recording a
decision, signing off, acknowledging an escalation, filing an
attestation - is written to orboto's audit log with the actor and the
details. None of these tools exist to make you do more process for its
own sake; they exist so that when someone asks for evidence of the
process you already run, you can export it instead of reconstructing it
from memory. Both the risk register and the decision log offer a direct
**Export** button for exactly this - a machine-readable evidence dump
you can hand to an auditor or attach to a customer questionnaire
response.

## Edition note [#edition-note]

Governance tools are an **Enterprise** feature. On Community and
Business editions the pages and API routes still work, and every action
still gets recorded - but a soft-warn indicator appears on the License
page once you actually start using them (creating a risk, recording a
decision, and so on). Nothing you enter is ever blocked or hidden;
Enterprise unlocks the license without the reminder banner, not the
underlying functionality.

## Permissions [#permissions]

Each surface gates independently: reading needs the matching `:read`
permission (`admin:risk:read`, `admin:decision:read`,
`admin:oncall:read`, `admin:escalation:read`), mutating needs the
`:write` counterpart. A user who can read risks but not decisions, for
example, sees only the risk register card on this page - the others
simply don't render for them.


# On-call and escalations (/admin/governance/on-call-and-escalations)



Governance isn't just about paperwork after the fact - it's also about
making sure that when something actually goes wrong, a specific,
accountable human finds out, instead of an alert quietly expiring
unread. **On-call rotations** and **escalation ladders** are the
mechanism: this page explains the concepts and, specifically, how
*automated* triggers - not a person noticing something and manually
raising an alarm - end up reaching a human being.

Both live on **Admin -> SLA & escalation**, alongside SLA (response-time)
policies. For the complete field-by-field setup walkthrough - building a
schedule, building a ladder tier by tier, every option and its effect -
see [Alerts and SLA](/admin/operations/alerts-and-sla); this page
focuses on the concepts and the governance angle: accountability, and
how a machine-detected problem finds its way to a person.

## On-call, from zero [#on-call-from-zero]

**On-call** means: at any given moment, exactly one person is
designated as responsible for responding if something needs a human
right now. An **on-call rotation** automates *who* that is over time - a
round-robin list of people who hand the responsibility to the next
person on a schedule (say, weekly), so responsibility for "who gets
paged at 3am" is a standing, known answer rather than something decided
ad hoc every time an incident happens.

This matters for governance specifically because it converts "someone
should probably notice this eventually" into a named, accountable
person at every point in time - which is exactly the kind of thing an
auditor, or your own leadership, will ask to see evidence of.

## Escalation ladders, from zero [#escalation-ladders-from-zero]

An **escalation ladder** is an ordered chain of response tiers: tier 0
notifies someone immediately; if nobody acknowledges within that tier's
configured delay, tier 1 fires; if that's also unacknowledged after its
own delay, tier 2 fires, and so on. Each tier's target can be a specific
fixed person, everyone holding a given project role, or - tying back to
the previous section - whoever the on-call rotation says is currently on
duty.

The point of a ladder is resilience against a single point of failure:
if the first person notified is asleep, on vacation, or simply misses
the notification, the problem doesn't just sit unacknowledged - it
climbs to the next tier automatically until *someone* acknowledges it.

## How agent and system triggers reach a human [#how-agent-and-system-triggers-reach-a-human]

This is the part that's specific to a workspace where a meaningful
share of the work - and the *monitoring* of that work - is automated.
orboto's [alert rules](/admin/operations/alerts-and-sla#building-an-alert-rule-per-project)
watch for conditions nobody has to notice by hand: a budget crossing a
threshold, a ticket sitting stuck in one status too long, a milestone's
AI-generated risk assessment flipping to red, a sprint gone quiet with
no activity. None of these require a person to be watching - they're
evaluated automatically, either the instant the triggering change
happens or on a recurring schedule, and several of them are themselves
the product of orboto's own AI analysis (the AI risk assessment trigger
being the clearest example: an automated judgment about a milestone,
not a human opinion).

An SLA breach - a ticket's response or resolution timer running out -
is the same story from a different angle: it's the *system* detecting
that a commitment is at risk, not a person who happened to check.

Both of these - a fired alert, and an SLA breach - can be wired to an
**escalation ladder** so the automated detection doesn't stop at "a
notification was sent and might get read eventually." Once wired, the
ladder guarantees the chain above: tier 0 fires, and if nobody
acknowledges, it keeps climbing until it reaches someone who does. This
is the concrete answer to "how does an agent or an automated check
actually get a human's attention" - it's not a side channel or a hope
that someone reads a notification feed; it's the same escalation
machinery either way, whether the thing that noticed the problem was a
person, an alert rule, or an AI risk assessment.

{/* screenshot: Admin - SLA & escalation page, a running escalation instance showing its current tier and reason */}

## The governance record [#the-governance-record]

Every escalation **instance** - a live, in-progress climb up a ladder -
has a status (active, acknowledged, resolved, or exhausted if every
tier fired with no response) and, crucially, is recorded: who
acknowledged it and when. Combined with the on-call schedule's own
history of who was on duty at any given moment, this is what lets you
answer "who was responsible when this happened, and did they respond"
after the fact - not just "we have an on-call rotation" as a policy
statement, but a factual record of it functioning (or not) for any
specific incident.

## Setting it up [#setting-it-up]

The step-by-step for both surfaces - creating an on-call schedule,
adding members, setting a rotation length and hand-off time; building a
ladder tier by tier with delays and targets; wiring an SLA policy to a
ladder - lives in
[Alerts and SLA](/admin/operations/alerts-and-sla#escalation-ladders).
This page intentionally doesn't repeat those steps; come here for the
concept and the governance framing, go there to actually build one.

## Permissions [#permissions]

Reading on-call schedules requires `admin:oncall:read`; reading
escalation policies and their running instances requires
`admin:escalation:read`. Managing schedules, members, and overrides
requires `admin:oncall:write`; managing ladders and acknowledging a
running instance both require `admin:escalation:write` (acknowledging
changes escalation state, so it needs the write permission even though
it isn't editing the policy itself). Every mutation on either surface is
audit-logged.

## Troubleshooting [#troubleshooting]

For symptom-level troubleshooting (a rule that never fires, a timer
that shows breached with no notification, an on-call tier resolving to
the wrong person), see the **Troubleshooting** section of
[Alerts and SLA](/admin/operations/alerts-and-sla#troubleshooting) -
it covers both surfaces in depth since the day-to-day debugging is
identical regardless of which admin section you read the concept from.

One governance-specific point worth calling out here: **an escalation
instance's audit trail is only as good as someone actually acknowledging
it**. A ladder that fires and exhausts every tier with no acknowledgment
still leaves a complete record that nobody responded - which is exactly
the situation a periodic governance review should be checking for, not
something to notice only when an auditor asks.


# Risk register (/admin/governance/risk-register)



## What a risk register is [#what-a-risk-register-is]

A **risk register** is a running list of things that could go wrong -
for a project, a team, or a whole organization - tracked deliberately
instead of living only in people's heads until one of them actually
happens. Each entry records what the risk is, how likely it is, how bad
it would be if it happened, who owns watching it, and what the plan is
if it starts to materialize. The value isn't the list itself; it's that
writing risks down forces someone to actually decide what to do about
each one, and revisiting the list on a schedule catches a risk that's
quietly gotten worse before it becomes an incident.

## The likelihood x impact matrix [#the-likelihood-x-impact-matrix]

Every risk gets two independent 1-5 ratings:

* **Likelihood** - how probable is it that this risk actually occurs?
* **Impact** - if it does occur, how bad is the consequence?

orboto multiplies the two into a **score** (1-25) automatically - a
risk rated 5 likelihood x 5 impact scores 25 (as severe as it gets),
while a 1 x 1 scores 1 (barely worth tracking). The register's matrix
view plots every open risk on a 5x5 grid so the highest-priority risks
(top-right: likely *and* severe) are visually obvious at a glance rather
than buried in a sorted list.

{/* screenshot: Admin - Governance page, Risk register card with the likelihood x impact matrix populated */}

## Fields, explained [#fields-explained]

* **Title** - a short, specific description of the risk (e.g. "Primary
  hosting provider outage during peak season").
* **Description** (optional) - more detail on the risk itself.
* **Category** - security / schedule / financial / operational /
  compliance / technical / other.
* **Likelihood** and **Impact** - the 1-5 ratings above.
* **Status** - open / mitigating / monitoring / accepted / closed (see
  below).
* **Owner** (optional) - the person responsible for watching this risk
  and driving its mitigation.
* **Mitigation plan** (optional) - what you're doing (or would do) to
  reduce the risk's likelihood or impact.
* **Review cadence** (optional, in days) - how often this risk should be
  formally re-assessed. See below.
* **Linked project / milestone / ticket** (optional) - ties the risk to
  the concrete work it relates to.

## Recording a risk [#recording-a-risk]

1. Open **Admin -> Governance** and use the **Risk register** card.
2. Enter a title, pick a category, and set the **likelihood** and
   **impact** ratings (1-5 each).
3. Optionally set a **review cadence** in days - how often you want to
   be reminded to reassess this risk.
4. Click **Add risk**.

## Status [#status]

| Status     | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| Open       | Identified, not yet being actively mitigated                              |
| Mitigating | Actively being worked on                                                  |
| Monitoring | Under a watch, not currently being actively worked                        |
| Accepted   | A conscious decision to accept the risk as-is, without further mitigation |
| Closed     | No longer a live risk                                                     |

**Accepted** deserves a specific note: it isn't "we forgot about this."
It's a deliberate record that someone with the authority to do so looked
at this risk and decided the cost of mitigating it wasn't worth it
relative to its likelihood and impact - which is itself useful evidence
that risk was considered, not ignored.

## Review cadence [#review-cadence]

A risk with a **review cadence** set gets a **next review** date, and
the register flags it once that date is reached or passed - either
**Review overdue** or **Review** followed by the due date, right on the
risk's own row, so a stale risk assessment is visible without hunting
for it. Click
**Mark reviewed** to re-assess it: optionally update the likelihood,
impact, or status as part of the same action, plus an optional note
about what changed (or didn't) since the last review. This resets the
next-review clock from the review date, not the original creation date,
so the cadence stays consistent going forward.

A risk with **no** cadence set simply never gets flagged for review -
appropriate for something you genuinely just want a record of, not an
ongoing watch.

## Closing a risk [#closing-a-risk]

**Close** ends a risk's active life once it's genuinely no longer
relevant (the underlying condition that created it is gone, or it
happened and is now being handled as an incident rather than a risk).
Closing records who closed it and when, distinct from **Accepted**
status above - closed means "this is done," accepted means "this is
ongoing, and we've chosen to live with it."

## Exporting for evidence [#exporting-for-evidence]

Click **Export** on the Risk register card to download every risk - open
and closed, full detail - as a machine-readable file, for the same
audit/customer-questionnaire purpose as the Decision log's export.

## Permissions [#permissions]

Reading the register requires `admin:risk:read`; creating, updating,
reviewing, closing, and deleting risks all require `admin:risk:write`.
Every mutation, including each review, is written to the audit log.

## Troubleshooting [#troubleshooting]

* **A risk I closed still shows in the matrix view** - the matrix
  typically reflects open risks by default; switch the register's
  filter to include closed risks if you need to see the full historical
  picture rather than just what's currently live.
* **The review-overdue flag won't clear even though I discussed the
  risk in a meeting** - discussing it isn't the same as recording the
  review; click **Mark reviewed** on the risk itself to reset its
  next-review date, even if you're keeping the likelihood, impact, and
  status unchanged.
* **I can't tell why a risk scored what it did** - the score is always
  likelihood x impact, computed automatically; if the number looks
  wrong, check the two underlying 1-5 ratings rather than the score
  field itself, since the score isn't independently editable.
* **A risk that should clearly be top-priority isn't showing near the
  top-right of the matrix** - double-check its likelihood and impact
  values were actually set to reflect that; a risk that reads as severe
  in its description but was rated 2x2 will plot low regardless of how
  it sounds in prose.


# API keys (/admin/identity/api-keys)



API keys authenticate programmatic access - scripts, integrations, CLI
sessions and AI agents. A key is shown **once** at creation; orboto stores
only a hash. Keys have the form `orb_...` and are sent as
`Authorization: Bearer <key>`.

## Minting a key [#minting-a-key]

* **For yourself** - from your **Profile → API keys** section. The key
  acts with your own permissions.
* **For a bot** - administrators mint keys on a bot account's behalf from
  &#x2A;*Admin → Users →*&#x2A; the bot's row **→ API keys** tab. The key acts with
  the bot's project memberships and roles, not the admin's.

Every key gets a **name** (so you can tell integrations apart) and an
optional **expiry date**. Admin-minted keys default their **agent** flag
to the account type - a bot's key is an agent key unless you say
otherwise; self-service keys default to off and you opt in explicitly.

{/* screenshot: the API keys tab on a user's edit dialog with the new-key form open */}

## Agent profiles [#agent-profiles]

When a key is marked as an **agent key**, an admin minting it on a bot's
behalf can also set:

* **Agent kind** - a free-text label such as `coding`, `orchestrator`,
  `reviewer`, `runner` or `chat`.
* **Model tier** - `frontier`, `standard` or `small`.

Workspace rules for agents can target these attributes, so a lightweight
worker gets a different instruction set than an orchestrator - without
the agent declaring anything per call. Marking a key as an agent key also
makes work-routing policies apply to it: human-reserved tickets are
withheld from autonomous pulls, and the workspace's autonomy-pause
switches take effect. The agent kind and model tier fields are only
available on admin-minted bot keys, not on self-service keys from your
own profile.

## Rotating and revoking [#rotating-and-revoking]

* **Rotate** issues a fresh secret for the same key row (same name, same
  agent profile) and immediately invalidates the old secret - use this
  instead of creating a new key when you just need a fresh credential.
* **Delete** removes a key outright; access is cut instantly.
* Deactivating the owning user or bot invalidates all of their keys.

One key per integration or agent lane - never share a key across systems,
so a compromised or misbehaving integration can be revoked without
affecting the others.

## Monitoring usage [#monitoring-usage]

**Admin → API keys** is a workspace-wide, live-updating dashboard of every
key's request volume - not where you create keys. It shows, per key: the
owner, total requests, a share-of-traffic bar, last-used time and expiry,
searchable and sortable. Keys are flagged automatically:

| Flag          | Meaning                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| **Dominant**  | This key accounts for ≥20% of all requests (and >100 requests) - worth checking it's not a runaway loop. |
| **Stale**     | No requests in the last 90 days - a candidate for cleanup.                                               |
| **Expired**   | Past its expiry date. Still shown for visibility even though it no longer authenticates.                 |
| **Suspended** | The owning user or bot is deactivated - the key 401s regardless of its own state.                        |

{/* screenshot: the Admin → API keys dashboard with a dominant-key flag visible */}

## Troubleshooting [#troubleshooting]

**A key stopped working with no visible change to the key itself.** Check
**Admin → API keys** for a **Suspended** or **Expired** flag - the owning
account may have been deactivated, or the expiry date passed.

**One key is responsible for most of the traffic.** The **Dominant** flag
surfaces this automatically; check whether that's an expected orchestrator
key or a misbehaving loop retrying without backoff.

**An agent isn't getting the instruction set you expected.** Confirm the
key's **agent kind** and **model tier** match what your workspace rules
target - these are set on admin-minted bot keys only, under the user's
**API keys** tab.


# Bulk user management (/admin/identity/bulk-user-management)



For onboarding many accounts at once, moving between environments, or
periodic backups of the roster itself, **Admin → Users** offers three bulk
tools alongside the per-user create/edit flow described in
[Users, roles and permissions](/admin/identity/users-and-roles).

## Export [#export]

**Export** downloads a ZIP archive of user accounts.

* **All users** (default) - the whole roster.
* **Selection** - search and check individual accounts (bot and guest
  accounts are labelled in the picker).

{/* screenshot: the export dialog with the all-users / selection mode toggle */}

## Import [#import]

**Import** accepts a ZIP in the same shape the export produces - useful
for restoring a roster or moving accounts between orboto instances.

1. Drop or browse to the file.
2. Pick a **conflict policy** for rows that match an existing email:
   * **Update** - overwrite the existing account's fields.
   * **Skip** - leave existing accounts untouched, only create new ones.
   * **Fail** - abort the whole import if any row conflicts.
3. **Preview** runs a dry run and reports how many rows would be created,
   updated or skipped, plus any conflicts or warnings.
4. **Apply** runs it for real. Changing the conflict policy after a
   preview invalidates it - re-run Preview before applying.

{/* screenshot: the import dialog showing a preview with created / updated / skipped counts */}

## Bulk-map GitHub usernames [#bulk-map-github-usernames]

**GitHub CSV** bulk-sets the GitHub username used for commit/PR
attribution and assignee sync, without editing each user individually.
Upload a CSV with `email` and `github_login` columns; rows are matched by
email. The result reports how many were updated, which emails weren't
found, and which rows were invalid (bad GitHub username format, or a
login already mapped to another user).

{/* screenshot: the GitHub-username CSV upload dialog with a result summary */}

## Troubleshooting [#troubleshooting]

**Import preview looks right, but Apply is disabled.** You changed the
conflict policy after previewing - the plan is now stale. Run Preview
again with the current policy, then Apply.

**GitHub CSV reports "not found" for emails you know exist.** The match is
exact and case-sensitive on the stored email address. Export your users
first to confirm the exact casing on file.

**Import created duplicate accounts instead of updating.** Check the
conflict policy was actually **Update** - **Skip** intentionally leaves
existing accounts untouched, and **Fail** aborts the whole run rather than
skip past a conflict.


# Single sign-on (OIDC and SAML) (/admin/identity/sso)



orboto supports SSO via OIDC and SAML 2.0, configured entirely from
**Admin → SSO** - no config-file edits, no REST calls needed.

## Add a provider [#add-a-provider]

**Admin → SSO → Add provider** opens a form gated by protocol:

{/* screenshot: the add-provider form with the OIDC/SAML protocol toggle */}

* **OIDC** needs the **issuer URL**, **client ID** and **client secret**
  from the IdP's app registration, the **scopes** to request (default
  `openid profile email`), and which claims map to orboto's `email` and
  `fullName` fields.
* **SAML 2.0** needs the IdP's **entity ID**, **SSO URL** and optional
  **SLO URL**, the IdP's &#x2A;*signing certificate (PEM)**, an &#x2A;*SP private
  key (PEM)** to sign outbound requests and the metadata document, the
  **NameID format**, and which assertion attributes map to `email` and
  `fullName`.
* Both protocols also take a **label** (shown on the login button),
  **allowed domains**, **enforce for domains**, and a **default JIT
  role** assigned on a user's first SSO login.

Once created, expand the provider row to copy the **ACS / redirect URI**
(OIDC callback or SAML ACS URL) and, for SAML, the **SP metadata URL** -
paste these into the IdP's trust configuration. The expanded row also
lets you edit the label, domain lists and default role in place.

**Secrets are write-only after save.** To rotate a client secret, IdP
certificate or SP private key, delete the provider and re-create it with
the new value - there's no in-place secret rotation yet.

## Secrets at rest [#secrets-at-rest]

Per-provider credentials - OIDC client secrets, SAML IDP certificates,
SAML SP private keys - are sealed with AES-256-GCM before they touch the
database. The key is derived from `SSO_ENC_SECRET`.

* **Coolify one-click install**: `docker-compose.yml` binds
  `SSO_ENC_SECRET` to the Coolify magic variable
  `SERVICE_PASSWORD_64_SSO`, auto-generated on first deploy - you don't
  set it yourself.
* **Manual deploys**: set `SSO_ENC_SECRET` to a random 64-character
  string and treat it like `JWT_SECRET`. Losing it means every stored
  provider config becomes unreadable and every SSO-bound user falls back
  to password login (which may be disabled for their domain).
* **Rotating it is destructive** - every stored config becomes
  undecryptable, and affected providers show a red "configuration can't
  be decrypted" banner. Rotation procedure: announce a maintenance
  window, delete every affected provider in the admin UI, rotate the
  secret, restart the API, re-create each provider. Super-admin
  password login keeps working throughout (see below).

## Enforcement model [#enforcement-model]

Each provider has two domain lists:

* **Allowed domains** - which email domains may use this provider. Empty
  \= unrestricted.
* **Enforce for domains** - which domains MUST use this provider. Users
  on these domains can't log in with a password at all.

`enforce_for_domains` is the lock-in feature for Business/Enterprise - it
prevents "vanity accounts" where someone sets up a personal password on
their company email. Without it, password login stays available
alongside SSO as a fallback.

### Super-admin bypass [#super-admin-bypass]

Users with the global **super-admin** role are always exempt from
`enforce_for_domains` - password login keeps working for them regardless
of domain restrictions. This mirrors GitLab, GitHub Enterprise and Sentry:
a local-credential path for the platform-root admin so a misconfigured
IdP can't lock the whole system out.

Every super-admin is a "break-glass" account for SSO enforcement - audit
who holds the role regularly, and don't issue it to operational staff
just because it's convenient.

## Login log [#login-log]

**Admin → SSO → Login log** records every handshake - success, signature
failure, or domain-mismatch rejection - filterable by provider. Check
this first when a provider "isn't working": a spike of one error code
usually points straight at the cause (see Troubleshooting below).

{/* screenshot: the SSO login log filtered to one provider showing a mix of success and failure rows */}

## Troubleshooting [#troubleshooting]

### A single super-admin forgot their password [#a-single-super-admin-forgot-their-password]

They use the normal forgot-password flow on the login page. Super-admins
are domain-enforcement-exempt by design, so the reset email goes out even
if every non-super-admin is SSO-enforced.

### The super-admin's IdP went down mid-login [#the-super-admins-idp-went-down-mid-login]

Their password login still works (see the bypass rule above). Sign in
with email + password, check the provider's status in **Admin → SSO**,
and toggle it inactive if you need to keep non-super-admins out until the
IdP is back.

### The super-admin also forgot their password (no self-service path) [#the-super-admin-also-forgot-their-password-no-self-service-path]

Run the CLI recovery tool on the host (SSH to the API container or host
machine):

```bash
pnpm --filter @orboto/api admin:reset-password <email>
```

This mints a single-use, 30-minute-TTL password-reset token and prints
the reset URL to stdout. Forward it to the super-admin out-of-band
(phone, Signal) - **do not email it**, since the point of this path is
that the email system might itself be broken. The tool refuses to run for
non-super-admin accounts and requires host access; there's no remote
invocation path.

### The only super-admin lost their password and can't reach the host [#the-only-super-admin-lost-their-password-and-cant-reach-the-host]

Recoverable only with direct database access:

```sql
UPDATE users
  SET password_hash = '$2a$12$<bcrypt-hash-of-temporary-password>'
  WHERE email = 'admin@example.com';
```

Generate the bcrypt hash separately (for example
`node -e "require('bcryptjs').hash('temp-pw', 12).then(console.log)"`).
After login, change the password immediately via Profile → Password. This
is the last resort - reality doesn't guarantee anyone has both host access
and a remembered password at the moment of panic.

### A cert rotation or clock skew broke logins for one provider [#a-cert-rotation-or-clock-skew-broke-logins-for-one-provider]

Filter the login log to that provider. `invalid_signature` points at a
rotated IdP certificate (re-import it); `invalid_state` usually means
clock skew or an abuse attempt; `domain_mismatch` means the login email's
domain isn't on that provider's allowed-domains list.

### Deleting a provider [#deleting-a-provider]

Deleting a provider unbinds every user tied to it (their row stays, just
without an SSO identity) and immediately fails any in-flight login for
that provider. JIT-provisioned users have a random password hash, so they
can't fall back to password login until you send them a reset link -
communicate that before deleting a provider that JIT-created accounts.

## Licensing [#licensing]

No license gate ships on SSO today - every install can use it out of the
box.


# Two-factor authentication (/admin/identity/two-factor)



orboto has native time-based one-time-password (TOTP) two-factor
authentication. A user pairs an authenticator app (Google Authenticator,
1Password, Aegis, etc.), and from then on a 6-digit code is required as a
second step after the password at sign-in.

This is a Business/Enterprise feature. On the Community plan it works but
raises a soft-warn on the License page; nothing is blocked.

It is standard RFC 6238 TOTP: HMAC-SHA1, 30-second step, 6 digits, with a
±1 step tolerance for clock drift. Any compliant authenticator app works -
there is no orboto-specific app to install.

## For users [#for-users]

### Enrol [#enrol]

1. Go to **Profile → Two-factor authentication** and click **Enable 2FA**.
2. Scan the QR code with your authenticator app, or type the shown secret
   key in manually.
3. Enter the current 6-digit code to confirm. 2FA is now on.
4. **Save your backup codes.** Ten one-time codes are shown *once*, right
   after you confirm. Copy or download them and store them somewhere safe
   (a password manager). Each code works exactly once.

{/* screenshot: the 2FA enrolment dialog showing the QR code and the backup-codes list */}

### Sign in with 2FA on [#sign-in-with-2fa-on]

After your email + password are accepted, orboto asks for your
authentication code. Open your authenticator app and enter the current
6-digit code. If you don't have your device, enter one of your backup
codes in the same field instead.

Too many wrong codes in a row temporarily locks the code step for a few
minutes (brute-force protection). Wait, then try again with a fresh code.

### Disable [#disable]

**Profile → Two-factor authentication → Disable 2FA**, then enter a
current code or a backup code. This removes your secret and all remaining
backup codes.

### Lost your device *and* your backup codes [#lost-your-device-and-your-backup-codes]

Ask a workspace admin to reset your 2FA (see below). After a reset you
sign in with your password only, and should immediately enrol again -
especially if the workspace requires 2FA.

## For admins [#for-admins]

### Reset a user's 2FA [#reset-a-users-2fa]

**Admin → Users →*&#x2A; the user's row **→ Reset 2FA**. This clears the
user's TOTP secret and backup codes; you can optionally add a reason,
which is shown to the affected user. It's reversible in the sense that
the user can simply enrol again - it does not expose any secret.

Resetting someone else's 2FA is a takeover-adjacent action: it requires
`admin:users:write`, **and** you must have completed your own MFA
challenge recently (a step-up check) before the reset goes through. If
the user had 2FA enabled, they're notified in-app and by email that an
admin disabled it.

{/* screenshot: the row menu with the Reset 2FA action and the optional-reason prompt */}

### Require 2FA for the workspace [#require-2fa-for-the-workspace]

**Admin → Security** has an **MFA enforcement** card with three modes:

* **Off** - nobody is required to have 2FA.
* **All** - every local (password) account must enrol.
* **Roles** - only accounts holding the listed global roles must enrol
  (for example `super-admin, admin`).

Two more settings apply whenever a mode other than Off is active:

* **Exempt SSO accounts** (on by default) - see below.
* **Grace days** - how many days a newly-covered account gets to enrol
  before being blocked. `0` means immediate enforcement.

A blocked account can only reach the 2FA setup flow, sign-out, and its own
profile until it enrols. The same card shows a **compliance table**: every
active user, their global roles, and whether 2FA is currently on - useful
for confirming a rollout actually landed before you tighten the grace
period.

{/* screenshot: the MFA enforcement card in Admin → Security with the mode picker and compliance table */}

Reading the policy requires `admin:system:read`; changing it requires
`admin:system:write`.

## SSO and 2FA [#sso-and-2fa]

The enforcement policy applies to **local password accounts**. Users who
sign in through SSO (OIDC / SAML) are, by default, not asked for an
orboto TOTP code and not subject to the policy - their second factor is
enforced by your identity provider, which is where it belongs. Uncheck
**Exempt SSO accounts** in the enforcement policy if you want SSO users
covered too. Configure MFA on the IdP side via
[SSO setup](/admin/identity/sso).

A user who has both a password and an SSO identity, signing in with the
password on a domain that isn't SSO-enforced, is treated as a local
account and is subject to the policy.

## How it works (operator notes) [#how-it-works-operator-notes]

* The TOTP secret is stored AES-256-GCM-encrypted, keyed from
  `MFA_ENC_SECRET` (falling back to `JWT_SECRET` if unset). Set a
  dedicated `MFA_ENC_SECRET` in production and rotate it like any other
  secret - rotating it invalidates existing enrolments, and users re-enrol.
* Backup codes are stored only as SHA-256 hashes; the plaintext is shown
  once at generation and never again. A backup code is single-use.
* Login is two-step: a correct password for a 2FA-enabled user yields a
  short-lived (5-minute) challenge token, not a session. The session is
  issued only after a valid TOTP or backup code is presented. The code
  step is rate-limited per account and additionally capped per IP.
* Backup-code count is fixed at ten and regenerated (replacing any prior
  set) every time 2FA is confirmed.

## Audit events [#audit-events]

| Action                       | When                                                                       |
| ---------------------------- | -------------------------------------------------------------------------- |
| `mfa.enabled`                | a user confirms enrolment                                                  |
| `mfa.disabled`               | a user disables their own 2FA                                              |
| `mfa.admin_reset`            | an admin resets a user's 2FA                                               |
| `auth.mfa_challenge_success` | a login challenge is passed                                                |
| `auth.mfa_challenge_failed`  | a wrong code at the login challenge (includes whether it tripped the lock) |

## Troubleshooting [#troubleshooting]

**Reset 2FA action is greyed out or fails.** You need a recent MFA
challenge of your own - sign out and back in (completing your own 2FA
step) before retrying, in addition to holding `admin:users:write`.

**A user is locked out even though "Exempt SSO accounts" is on.** That
exemption only applies to accounts actually bound to an SSO provider.
Someone with both a password and an SSO identity, signing in with the
password, is treated as local and stays covered by the policy.

**Rolled out enforcement but some accounts still show 2FA off.** Check
the **grace days** setting - accounts inside their grace window are
allowed to sign in without 2FA yet. The compliance table on the
enforcement card shows exactly who's still unenrolled.


# Users, roles and permissions (/admin/identity/users-and-roles)



## The permission model [#the-permission-model]

orboto uses fine-grained, permission-based access control. Every sensitive
action is gated by a **permission slug** like `ticket:edit`,
`milestone:view_private` or `admin:users:write`. Permissions are bundled
into **roles**; roles are granted either **per project** (project
membership) or **globally** (for admin areas).

* A **super-admin** global role passes every check - reserve it for very
  few people.
* Admin permissions are deliberately narrow (`admin:backup:read`,
  `admin:webhooks:write`, ...) so you can delegate one area without
  handing over the whole admin panel.
* Destructive rights are separate slugs from edit rights (for example
  `ticket:delete` is not implied by `ticket:edit`), so "can change" never
  silently means "can destroy".
* What a user cannot do, they also do not see - navigation entries and
  buttons are hidden along with the permission.

## Managing roles [#managing-roles]

**Admin → Roles** lists every role with its permission count. Click a role
to expand its permission matrix, grouped by family (ticket, comment, time,
users, admin, ...). Toggle a single permission, or use **Grant all /
Revoke all** on a family header - changes save immediately.

{/* screenshot: the role editor with an expanded permission family and the grant-all control */}

**New role** opens a form with:

* **Name** and **Scope** - Global (available everywhere) or Workspace (all
  projects in this workspace).
* **Start from preset** - `backup-operator`, `auditor`, `dsgvo-operator`,
  `developer` and `reporter` pre-check a sensible slug set you can adjust
  before saving.
* The same searchable permission matrix as the edit view.

Permissions carry small badges where relevant: **destructive** (an
irreversible action) and **deprecated** (kept for older integrations, not
recommended for new roles).

Pick which role templates auto-seed into every **new** project from the
**Default templates for new projects** panel above the role list.

## Creating users [#creating-users]

**Admin → Users → New user** offers two modes:

* **Invite by email** (default) - enter a name and email, pick an **invite
  scope** (whole workspace with a global role, a single project with a
  project role, or a single customer with a customer role), and send. The
  invitee sets their own password on first sign-in. Re-inviting an email
  that already has a pending invitation surfaces that invitation instead
  of creating a duplicate.
* **Create directly** - you set the password yourself (or generate a
  random one and copy it), with an option to email the credentials. Use
  this for bot accounts or when email delivery is unreliable.

{/* screenshot: the create-user dialog with the invite / direct-create mode toggle */}

If the invitation email can't be delivered, the dialog stays open and
shows the invite link directly so you can copy-paste it - resend it any
time from the **Pending invitations** tab.

### Bot accounts [#bot-accounts]

Bots are service identities for agents and integrations: they cannot sign
in with a password, they authenticate only via API keys minted for them,
and each bot has a **responsible human owner**. Give every agent,
integration and automation its own bot - presence, audit trails and rate
limits stay attributable, and revoking one integration never breaks
another. Bots can also be **paused**: a paused bot stops picking up work
on its own while explicitly assigned tasks keep working (see
[Agents & AI](/agents-ai)).

Bulk-creating or updating many accounts at once (from a spreadsheet or
another system)? See [Bulk user management](/admin/identity/bulk-user-management).

## Editing a user [#editing-a-user]

Open a row to edit across tabs:

* **Details** - avatar, name, email, hourly rate, an optional overhead
  factor override, and the GitHub username used for webhook attribution
  and assignee sync. Bot rows additionally show the responsible owner and
  an autonomy-pause switch. MCP (AI client) access is shown read-only here
  * the user controls that toggle from their own profile.
* **Schedule** - working days, hours and week start.
* **Access** - global roles (checkboxes) and project memberships, editable
  inline without leaving the dialog.
* **Features** - per-user overrides for surfaces that default by account
  type (work schedule, out-of-office delegation, time calendar): inherit
  the role default, or force show/hide.
* **Vacation** / **Sick leave** - balances and, for sick leave, who gets
  notified when this person reports sick.
* **Security** - reset the password: send a reset link, or set one
  directly (optionally emailing it).
* **API keys** - mint, rotate or delete keys on this user's behalf,
  including bot agent profiles. See [API keys](/admin/identity/api-keys).

{/* screenshot: the edit-user dialog showing the Access tab with global roles and project memberships */}

## Sessions [#sessions]

**Admin → Sessions** lists every active sign-in workspace-wide - user,
device, IP address, last activity and expiry - searchable by name or
email. Revoke a session after a suspected compromise; it takes effect
immediately. There's no single "revoke all" button - after a compromise,
search by the user's name and revoke each of their rows.

## Data protection [#data-protection]

Per user, administrators with the corresponding rights can:

* **Export** all personal data as a downloadable JSON file
  (`admin:dsgvo:export`).
* **Anonymize** an account - scrubs personal data but keeps the row (and
  their tickets, comments and audit trail) in place, attributed to an
  anonymous author (`admin:dsgvo:anonymize`). You must type `ANONYMIZE` to
  confirm. You can't anonymize your own account, and an account under
  legal hold can't be anonymized until the hold is lifted.

Both actions are audit-logged.

### Deactivate, reactivate, or delete [#deactivate-reactivate-or-delete]

Deactivating blocks sign-in immediately; reactivating restores it. **Hard
delete** (typing `delete <email>` to confirm) permanently removes the
account - sessions, comments, time entries, assignments and memberships
are wiped, while tickets they created, audit-log entries and attachments
stay with an anonymous author. Prefer **Anonymize** when you want the
workspace history intact but the person's data gone.

### Revoking AI-client access [#revoking-ai-client-access]

Separately from API keys, an admin can revoke all of a user's MCP (AI
client) OAuth grants and clear their MCP sessions - their AI clients
(Claude Desktop, Cursor, ...) must then re-authorize. Use this alongside
deactivation and session/API-key revocation when someone leaves.

## Troubleshooting [#troubleshooting]

**Deactivated a user, but their integration still works.** Deactivation
alone doesn't revoke sessions, API keys, or MCP grants - it blocks new
sign-ins. Also revoke their sessions (**Admin → Sessions**), delete their
API keys (the user's **API keys** tab), and revoke MCP grants if they used
AI clients.

**A permission checkbox change didn't seem to apply.** The role editor
saves each toggle immediately - refresh if the UI looks stale. Users with
that role need to sign out and back in only if their *session* carries
stale claims; most permission checks are read live from the database.

**Invited someone and nothing arrived.** Check the **Pending invitations**
tab first - if the invite exists, resend it or copy its link directly
instead of creating a new one (a duplicate invite for the same email
surfaces the existing one rather than sending twice).

**Can't anonymize an account.** Either it's your own account (not
allowed), or it's under legal hold - check **Admin → Compliance** for
active holds before anonymizing.


# Alerts and SLA (/admin/operations/alerts-and-sla)



Two related but separately-owned surfaces. **Alert rules** live per
project - a project admin builds them in that project's own settings,
because most conditions (budget, capacity, stuck tickets) only make
sense in the context of one project's data. **SLA policies, escalation
ladders and on-call rotations** are workspace admin surfaces under
**Admin -> SLA & escalation**, because they typically apply the same way
across every project a support or customer-facing team runs.

## Building an alert rule (per project) [#building-an-alert-rule-per-project]

{/* screenshot: Project Settings - Alerts, rule wizard step 1 (trigger picker) */}

Open a project's **Settings -> Alerts** tab and start the rule wizard - a
four-step flow: **Trigger -> Conditions -> Notification -> Review**.

### Step 1 - Trigger [#step-1---trigger]

Give the rule a **name** and pick a **trigger type** from the dropdown. A
one-line hint under the dropdown explains what each one watches:

| Trigger                 | Fires when                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| Budget threshold        | The project's spent budget crosses a percentage you set                                             |
| Estimate exceeded       | Logged time on a ticket exceeds its own estimate                                                    |
| User over capacity      | A person's assigned workload exceeds their configured capacity                                      |
| Ticket overdue          | An open ticket passes its due date                                                                  |
| Ticket stuck            | A ticket sits in one status too long                                                                |
| No sprint activity      | A milestone/sprint has had no activity for a stretch                                                |
| Milestone deadline risk | A milestone's remaining work makes its deadline unlikely, within a days-remaining threshold you set |
| AI risk assessment      | orboto's AI milestone-risk assessment flags a milestone red (or optionally yellow too)              |
| Timesheet not submitted | A user's timesheet is still open past its submission point                                          |
| Ticket created          | A new ticket is created - narrow with conditions below to catch specific intake patterns            |

Also pick the **severity** - info, warning, or critical - shown as a
colored badge everywhere the rule and its firings appear.

### Step 2 - Conditions [#step-2---conditions]

This step's fields change entirely based on the trigger you picked in
step 1:

* **Budget threshold / estimate exceeded / user over capacity** - a
  single **threshold** number (meaning depends on the trigger: a
  percentage for budget, a ratio for estimate/capacity).
* **Ticket overdue / ticket stuck** - checkboxes for which statuses count
  as "still open" for this rule's purposes (so, for example, a status
  you use as an explicit "waiting on customer" holding pen can be
  excluded from counting as overdue).
* **Milestone deadline risk** - **days remaining** before the deadline at
  which the rule should start firing.
* **AI risk assessment** - an **include yellow** checkbox: off (default)
  fires only when the AI assessment marks a milestone red; on also fires
  on yellow (at-risk, not yet critical), for teams that want the earlier
  warning.
* **Ticket created** - three independent, all-optional narrowing filters:
  restrict to specific **milestones**, restrict to tickets created by
  someone holding specific **project roles**, and/or a checkbox to only
  fire when the **creator is a guest/external account** - useful for
  flagging external intake for review before it's treated like internal
  work.

### Step 3 - Notification [#step-3---notification]

Pick who gets notified and how:

* **In-app** and/or **Email** delivery checkboxes.
* Specific **project roles** to notify (everyone currently holding that
  role gets it) and/or specific **individual users**.
* **Cooldown (minutes)** - once this rule fires, it won't fire again for
  the same underlying condition until the cooldown expires, even if the
  evaluation cycle runs again in the meantime. This is what keeps a
  persistent problem (a ticket that's been overdue for a week) from
  spamming a notification every single evaluation cycle - it alerts once
  per cooldown window, not once per check.

### Step 4 - Review [#step-4---review]

A summary of everything you picked across the previous three steps,
before you commit. Go back to any earlier step to adjust, or confirm to
create the rule - it's active immediately.

### Immediate vs. scheduled evaluation [#immediate-vs-scheduled-evaluation]

Budget threshold, estimate exceeded, user over capacity, ticket overdue,
and ticket created are **immediate** triggers - they fire right after the
change that caused them, not on a delay. Ticket stuck, no sprint
activity, milestone deadline risk, AI risk assessment, and timesheet not
submitted are evaluated **on a schedule** instead, since "has this been
true for a while" isn't a single point-in-time event to react to.

## SLA policies (Admin -> SLA & escalation) [#sla-policies-admin---sla--escalation]

{/* screenshot: Admin - SLA & escalation page, SLA policy card with the per-priority target grid */}

For teams with response-time commitments (support inboxes, customer
projects), open **Admin -> SLA & escalation** and use the **SLA
policies** card:

1. Enter a **policy name**.
2. Toggle **Business hours only** if targets should only count working
   time - weekends, public holidays, and configured company closures are
   excluded, using the same calendar the time-tracking module uses. Leave
   it off to count wall-clock time around the clock.
3. Set the &#x2A;*at-risk %** threshold (default 80) - the percentage of the
   target consumed at which a ticket flips to "at risk" so escalation can
   start before an actual breach, not after.
4. Fill in **response** and **resolution** targets, in minutes, per
   priority (blocker / high / normal / low / trivial) - leave any cell
   blank to not track that target for that priority at all.
5. Optionally attach an **escalation ladder** (see below) to hand off a
   breach automatically; pick "No escalation ladder on breach" to just
   track the SLA without any automated hand-off.
6. Click **Add policy**.

Every ticket in scope gets a live **SLA timer** the moment it qualifies,
shown running/paused/met/breached/cancelled in the **Running timers**
list at the bottom of the card. **Evaluate now** forces an immediate
re-check of every timer instead of waiting for the next scheduled pass -
useful right after creating or editing a policy to see its effect
immediately rather than waiting.

## Escalation ladders [#escalation-ladders]

{/* screenshot: Admin - SLA & escalation page, escalation ladder card with tiered targets */}

An escalation ladder is an ordered chain of **tiers**: tier 0 notifies
immediately when triggered, tier 1 fires after its own configured delay
if nobody has acknowledged yet, tier 2 after its delay, and so on.

Building one: name it, then for each tier set &#x2A;*delay (minutes)** - how
long to wait after the previous tier before escalating further - and a
**target**: a specific fixed user, everyone holding a given project role,
or whoever the on-call rotation currently says is on duty. Add as many
tiers as you need.

Once triggered (by an SLA breach, or standalone), an escalation shows up
as an **instance** with a status: **active** (still escalating),
**acknowledged** (someone stopped the chain), **resolved**, or
**exhausted** (every tier fired with no acknowledgment). **Acknowledge**
on an active instance stops it from advancing to the next tier - it does
NOT resolve the underlying ticket or SLA breach itself, it just stops the
notification chain.

## On-call rotations [#on-call-rotations]

A rotation defines a round-robin list of users, a **rotation length**
(days) before it hands off to the next person, and a daily **hand-off
time** (UTC). An escalation tier that targets "on call" always resolves
to whoever the currently-active rotation entry says is on duty at that
moment - keep the rotation's user list current, since a rotation with
nobody actually scheduled leaves that tier with no one to notify.

## Troubleshooting [#troubleshooting]

* **An alert rule never fires even though the condition is clearly met**
  * check the cooldown first: if the same condition already fired within
    the cooldown window, it's suppressed by design, not broken. Also
    confirm the rule lives on the right project - alert rules are
    per-project, never workspace-wide.
* **A scheduled-evaluation trigger (stuck, deadline risk, AI risk,
  timesheet) seems delayed** - these evaluate on a periodic schedule, not
  the instant the condition becomes true; an immediate trigger fires
  right away, a scheduled one waits for its next evaluation pass.
* **SLA timer shows breached but nobody was notified** - the SLA policy
  by itself doesn't send notifications; attach an escalation ladder to
  get an actual hand-off, or rely on a project alert rule targeting
  `ticket_overdue` if you just want a direct in-app/email ping without
  the tiered escalation machinery.
* **Escalation keeps re-notifying after someone already handled it** -
  acknowledge the specific escalation *instance* (not just resolving the
  underlying ticket) to stop the ladder from advancing to its next tier.
* **"On call" tier never resolves to the right person** - verify the
  rotation's hand-off time is genuinely in UTC as you expect, and that
  its user list is current; check whether the rotation even has an
  active schedule covering right now.
* **Business-hours SLA calculations look wrong** - they depend on the
  same blocked-days calendar as the time-tracking module; verify public
  holidays and company closures are configured correctly for the period
  in question.


# Audit log and tamper evidence (/admin/operations/audit-and-compliance)



This page covers the audit trail itself. For handing evidence to an
external auditor or SIEM, see
[Compliance exports and SIEM forwarding](/admin/operations/compliance-exports).
For GDPR data-subject requests, legal holds and retention, see
[Data protection](/admin/operations/data-protection).

## The audit log [#the-audit-log]

{/* screenshot: Admin - Audit log page, expanded row showing JSON detail */}

**Admin -> Audit log** records every sensitive action in the workspace:
sign-ins, permission changes, admin operations, data exports, and
deletions. Each entry shows the actor, the action, the target entity, and
the timestamp.

* **Filter by entity type** using the dropdown at the top (user, project,
  ticket, role, project federation, or "All"). This is the only filter
  on this page today - for a specific date range or actor, scan visually
  or use the compliance-export flow's date-ranged bundle instead.
* **Load more** at the bottom fetches the next page; the list is
  append-only and ordered newest-first, so scrolling further back always
  shows what happened earlier, never a shifting window.
* An entry performed by an AI agent (rather than a human clicking
  through the UI) carries a small **Agent** badge next to the actor's
  name - useful when auditing autonomous work specifically.
* Click the chevron on any row that has extra detail to expand it and see
  the full JSON payload of what changed - the exact before/after or
  parameters recorded for that action, not just the one-line summary.

Entries here are never edited or deleted through the UI - the log is
append-only by design, which is also why the tamper-evident chain below
is meaningful: nothing in the normal admin flow ever rewrites history.

## Tamper-evident hash chain [#tamper-evident-hash-chain]

{/* screenshot: Admin - Tamper-evident audit log page, chain status card with stats */}

Open **Admin -> Tamper-evident audit log**. This feature seals every
audit-log entry into an append-only cryptographic chain: each link's hash
covers that entry's content **plus** the previous link's hash. Because of
that chaining, changing, deleting, reordering, or inserting an entry
anywhere in the sequence changes every hash after it - which is exactly
what the **Verify integrity** check below detects.

### Reading the status card [#reading-the-status-card]

The top of the page shows four numbers:

* **Audit rows** - total entries in the audit log.
* **Sealed** - how many of them are already chained.
* **Pending** - how many exist but haven't been sealed into the chain
  yet (highlighted in amber if greater than zero - not alarming on its
  own, sealing runs on its own cadence, but worth knowing about before
  you rely on "everything is verified" being literally true at this
  instant).
* **Tail seq** - the sequence number of the most recently sealed link.

Below that, the **tail hash** is shown in full (truncated with an
ellipsis in the middle) - this is the single value that, if it matches
between two independent checks, proves nothing in the entire chain up to
that point has been altered.

### What each action does [#what-each-action-does]

* **Enable / Disable** (top-right of the status card) toggles whether new
  audit entries get sealed as they happen. Disabling does NOT invalidate
  anything already sealed - those links remain fully verifiable - it
  simply stops adding new ones until you re-enable it. Requires the
  audit-management write permission; a read-only auditor sees the status
  but not this button.
* **Seal pending now** force-seals whatever is currently pending, instead
  of waiting for the normal sealing cadence. Use this right before
  running a **Verify integrity** check if you want the verify to cover
  everything up to this exact second.
* **Verify integrity*&#x2A; walks the entire chain and reports one of two
  outcomes: &#x2A;*"Chain intact - N links verified"*&#x2A; (green), or &#x2A;*"Tampering
  detected at link N"** (red), with a specific **reason** and the exact
  **audit row id** implicated:
  * `content-mismatch` - the underlying audit row's stored content
    changed since it was sealed.
  * `missing-audit-row` - the audit row itself was deleted, but its chain
    link survives (deliberately - there's no foreign key tying the link
    to the row, precisely so a deletion shows up as a detectable gap
    instead of quietly taking the evidence of tampering down with it).
  * `seq-gap` - a link is missing from the sequence entirely.
  * `prev-hash-mismatch` - the chain of hashes doesn't connect at this
    point (broken continuity).
  * `row-hash-mismatch` - this specific link's own hash doesn't match
    what it should be, given its content and its predecessor.

This is available at every tier (the live chain itself, and running
Verify, are not gated). What Business/Enterprise adds on top is the
ability to hand a signed, portable copy of this evidence to an outside
auditor - covered on the next page.

## Troubleshooting [#troubleshooting]

* **Verify integrity reports a broken link** - note the exact sequence
  number and reason shown, then look up that specific audit row directly.
  Treat this as a genuine incident to investigate (who had database
  access, when), not something to retry past - retrying doesn't change
  what already happened to the row.
* **"Pending" never reaches zero** - if live chaining is disabled, this
  is expected; every new entry accumulates as pending until you
  re-enable it (which triggers sealing to catch up) or you click
  **Seal pending now**.
* **Filtering the audit log by entity type shows nothing for a type you
  expect to have entries** - double-check the exact entity-type string in
  the dropdown; some actions log under a more specific type than you
  might guess (e.g. a role change logs under `role`, not `user`).
* **An entry you expected to see an Agent badge on doesn't have one** -
  the badge only appears when the action was attributed to an AI-agent
  identity at the time it happened; a human who ran a script or CLI
  command under their own account shows as that human, not as an agent.


# Backups (/admin/operations/backup)



## What a backup contains [#what-a-backup-contains]

A full backup is a single archive: a manifest, every database table as
line-delimited JSON, and a copy of every stored file (attachments,
avatars). Derived data - search vectors, AI embeddings, cached
translations - is deliberately excluded and regenerated after a restore
instead of shipped in the archive, which keeps archives smaller and
portable even across different AI providers (a restore doesn't assume the
target has the same embedding model as the source).

## Creating a scheduled backup job [#creating-a-scheduled-backup-job]

{/* screenshot: Admin - Backup page, "New job" form */}

Go to **Admin -> Backup -> New job**. Fill in:

* **Name** - your own label, shown in the job list and on every run it
  produces.
* **Scope** - **Full** (the whole workspace) or **Project** (pick one
  project from the dropdown that appears).
* **Schedule** - a cron expression, with four quick presets (every day at
  03:00, every Sunday at 02:00, first of the month at 04:00, every hour)
  you can click instead of typing cron syntax by hand. Leave it blank if
  you only want to trigger this job manually.
* **Timezone override** - optional; leave blank to run on the workspace's
  own timezone (Admin -> System settings), or pick a different IANA zone
  for just this job.
* **Retention (days)** - how long completed runs from this job are kept
  before automatic cleanup.
* **Destination** - **Internal storage** (default) or **External S3
  bucket** (see below).
* **Contents** - what the job actually captures (see the table below).

Save, and the job appears in the list with a green dot (active). Click
**Run now** on any job at any time - before a risky upgrade, before a
bulk import - without waiting for its schedule.

### Destination: external S3 bucket [#destination-external-s3-bucket]

Any S3-compatible service works: AWS S3, Cloudflare R2, Backblaze B2,
MinIO, Hetzner Object Storage. Selecting **External S3 bucket** reveals:
endpoint (leave empty for AWS), region, bucket name, an optional path
prefix, access key, and secret. Click **Test connection** before saving -
it verifies the credentials actually work against that exact bucket,
catching a typo'd region or a permissions gap before your first scheduled
run fails at 3am. The secret is encrypted at rest and never returned by
the API; the edit form always shows it masked, and leaving it blank on
save keeps whatever is already stored - only typing a new value replaces
it.

### Content scope [#content-scope]

| Scope                  | What it produces                                                                                                                                                                                                                                                      | Best for                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Database + files       | The classic combined ZIP archive - every table as NDJSON plus every storage object together. Restorable as-is through the setup wizard or the Admin import button.                                                                                                    | Your primary, restorable backup                                 |
| Database only          | The same ZIP, without storage objects - small and fast.                                                                                                                                                                                                               | Frequent schedules (hourly/daily), paired with a Files-only job |
| Files only (S3 mirror) | No archive at all - external destinations only. Every owned storage object (attachments, avatars) is mirrored to `<prefix>/storage/<key>` in your bucket, incrementally by key + size. Nothing is ever deleted remotely, even if the object is later removed locally. | Cheap, frequent offsite copies of large attachment histories    |

A common offsite pattern is two jobs pointed at the same bucket: a daily
"Database only" job plus a daily "Files only" mirror job. The mirror only
transfers what's new or changed since last time, so daily runs stay cheap
even once the attachment history is large.

### Managed jobs [#managed-jobs]

On a hosted (Coolify-managed / cloud) instance, jobs the control plane
created for your plan show a **Managed** badge in the job list. You can
still **Run now** on a managed job, but pause, edit, and delete are
hidden for it - those stay under the platform's control.

## Manual full export [#manual-full-export]

The **Full backup now** button (top of the Backup page) downloads a
complete workspace archive immediately, completely outside any schedule.
Use it right before a version upgrade or any change you'd want a rollback
point for.

## Compliance exports [#compliance-exports]

Admins holding the DSGVO-export permission additionally see two buttons
here: a **DSGVO Art. 15 export** (a person's own personal-data export,
for a data-subject request) and a **BSI-C5 compliance PDF**. These are
distinct from the audit-trail evidence exports - see
[Audit and compliance](/admin/operations/audit-and-compliance) for
those.

## Run history [#run-history]

Every run - scheduled or manual - lands in **Recent runs**, with its
status (success / failed / running, with a spinner while in flight),
size, and start time. A run triggered by a job shows that job's name; a
manual full export shows as **Manual**. Each completed run offers
**Download** (grabs the archive) and **Delete** (removes just that run's
stored archive and history row - a simple confirm, since the run itself
carries no live data, only its own history entry).

## Restoring [#restoring]

There are two genuinely different restore paths, and picking the right
one matters:

### Full restore (whole workspace) [#full-restore-whole-workspace]

The reliable, always-works path is the **first-run setup wizard**: on a
brand-new instance, the wizard's first screen offers **Fresh setup**,
**Restore from a backup**, or **Import from a remote instance**. Pick
**Restore from a backup**, upload the archive, and enter the **setup
token** (a one-time value printed in the server's boot log, or set via
the `SETUP_TOKEN` environment variable - required so an unauthenticated
first-run screen can't be used to overwrite a running instance by
anyone who finds the URL). Click **Start restore**; you'll see a live
progress view (table-by-table row counts, then storage objects), and a
completion screen with the total rows and tables restored. Sign in
afterward with the credentials from the backup - not a new account.

You can also trigger a full restore directly from **Admin -> Backup ->
Import** on an already-running instance: upload the archive, and orboto
inspects it first (read-only) showing its kind, export date, orboto
version, total rows, and a per-table breakdown, before asking you to type
`WIPE-AND-RESTORE` to confirm. Be aware this path is guarded by a
fresh-instance safety check on the server side - it's built for restoring
onto an effectively-empty instance, and attempting it from an
already-populated, logged-in admin session can be refused by that guard.
If you hit that, use the setup-wizard path above instead, against a
genuinely fresh instance.

After any full restore, AI embeddings are automatically re-queued and
rebuild in the background - AI-dependent search features stay empty
until that finishes (or until you configure an AI provider, if none was
set on the source workspace).

### Project restore (one project) [#project-restore-one-project]

Use **Admin -> Backup -> Import** with a **project-scope** archive (one
created by a "Project" backup job, not a full one) - this path works on
any running instance, with no fresh-instance requirement. After
inspecting the archive, you pick:

* **Import as a new project** - creates a brand-new project from the
  archive; the default and safest choice.
* **Overwrite an existing project** - pick a target project from a
  searchable list, then type `OVERWRITE` to confirm. This wipes that
  project's current rows and replaces them with the archive's content
  while preserving the project's existing UUID (so anything referencing
  that project by ID, like a webhook subscription, keeps working
  afterward).

### Restoring from an S3-mirrored destination [#restoring-from-an-s3-mirrored-destination]

An archive sitting in your own S3 bucket restores exactly like a locally
downloaded one - download it and feed it into whichever restore path
above matches its scope. A "Database only" archive plus its paired
"Files only" mirror restore **together**: import the database archive
first through one of the paths above, then copy the mirrored objects
from `<prefix>/storage/` in your bucket into the instance's storage under
those exact same keys - the keys under that prefix ARE the original
storage keys, by design, so this is a straight copy, not a remap.

> Cloud workspaces are additionally backed up by the platform
> automatically, independent of anything configured here; the admin
> backup area still lets you export your own archives at any time for
> your own copy.

## Troubleshooting [#troubleshooting]

* **"WIPE-AND-RESTORE" full-restore fails on Admin -> Backup's Import
  button** - expected on an already-populated instance; the fresh-instance
  guard is load-bearing safety, not a bug to work around. Use the
  first-run setup wizard against a genuinely fresh instance instead.
* **S3 destination "Test connection" fails** - check the endpoint has no
  trailing slash, the region matches the bucket's actual region (some
  providers reject a mismatched region even when the endpoint itself is
  correct), and the access key has both write and list permissions on
  that specific bucket.
* **A mirror run reports failed objects** - the whole run is marked
  failed (and alerts like any failed backup job) if even one object
  couldn't be transferred; check the bucket's own access logs or storage
  quota before simply re-running it.
* **Retention isn't shrinking your bucket's usage** - `retentionDays`
  only governs the instance's own internal storage cleanup. Objects
  living in your own external bucket are yours to manage - set a
  lifecycle rule on the bucket itself if you want them expired.
* **Search / AI features stay empty right after a restore** - expected
  immediately after any restore; embeddings regenerate in the background.
  If it's been a while with no visible progress, check Admin -> AI
  settings for the re-embed status, or confirm an AI provider is actually
  configured on the restored instance.
* **Setup-wizard restore rejects the setup token** - it must match either
  the value printed in the server's boot log at startup or the
  `SETUP_TOKEN` environment variable if one was set; a stale value copied
  from an earlier boot won't work after a restart regenerated it.


# Compliance exports and SIEM forwarding (/admin/operations/compliance-exports)



Two ways to get audit evidence out of orboto and into someone else's
hands: a one-off downloadable bundle for an audit, or a continuous
real-time stream into your own security tooling. Both build on the audit
log and its [tamper-evident hash chain](/admin/operations/audit-and-compliance)
rather than inventing separate evidence.

## Generating a compliance evidence export [#generating-a-compliance-evidence-export]

{/* screenshot: Admin - Compliance evidence export page, "New export" form */}

Open **Admin -> Compliance evidence export**. Under **New export**:

1. Pick a **range start** and **range end** date.
2. Pick a **format** from the dropdown, grouped into two families:
   * **Evidence bundle (NDJSON)** - **BSI-C5** or **SOC-2**. Each is a
     ZIP containing the audit log, the SSO login log, and the error log
     for the chosen range, plus a manifest with a sha256 integrity hash
     per file inside.
   * **Signed / tamper-evident (auditor)** - reuses the hash chain's own
     hashes rather than computing new ones: **Signed CSV** (one CSV file
     where every row is individually Ed25519-signed over its chain hash,
     plus one signature for the whole file), **Hash-chained JSON-Lines**
     (one JSON object per line, each carrying its own `prev_hash`,
     `hash`, and `signature`), **Category bundle** (separate signed CSVs
     split by category - login, permission-change, data-access,
     config-change, and so on - handy when an auditor only wants one
     category), or **Auditor pack** (all of the above together, plus the
     public key and the offline verifier script - the single file to
     hand over when you don't know in advance exactly what format the
     auditor's tooling wants).
3. Click **Generate export**. Building a bundle for a large date range
   can take a moment - a note says so, and asks you not to close the
   page; the export appears in the **History** table below once it's
   ready.

Every signed export ships as a self-contained ZIP carrying `public-key.pem`
and a `manifest.json` with the export's own signature, its `bundleHash`,
the signing key's id, the row count, and the chain's tail hash at export
time - a complete chain of custody an auditor can check without any
access to your live orboto instance at all.

### History, verifying, and downloading [#history-verifying-and-downloading]

Each row in **History** shows the format, date range, status, size, and
creation time. For a completed **signed** export specifically, a
**Verify** button appears - it re-checks the export's own signature and
hash chain server-side and shows a pass/fail result inline, so you can
confirm an export is good before you send it anywhere. **Download** works
on any completed export regardless of format.

### The signing key [#the-signing-key]

A card on the same page shows the workspace's current **Ed25519 signing
key** (used for every signed export) and a **Rotate** button. Rotating
generates a new key for future exports; **old keys are kept on file**, so
exports signed before a rotation stay verifiable against the historical
key, not just the current one.

## Offline verification (for the auditor) [#offline-verification-for-the-auditor]

The auditor pack includes `verify-audit-export.mjs`, a single
dependency-free Node.js script - also downloadable on its own from this
page. The auditor runs it on their own machine, with no network access to
your orboto instance and no orboto runtime installed at all:

```
node verify-audit-export.mjs audit-log.jsonl public-key.pem
```

It exits `0` for a valid, untampered export (and prints nothing alarming);
`1` if tampering is detected, printing exactly which row and why; `2` for
a script-level error (wrong file, corrupted download). It re-implements
the identical canonicalization and hash-chaining rules the server uses,
so a clean offline run matches the server's own `Verify` result
byte-for-byte - nobody has to trust orboto's own claim that an export is
valid.

## SIEM forwarding [#siem-forwarding]

{/* screenshot: Admin - SIEM audit forwarding page, forwarder list with a test-send button */}

**Admin -> Audit forwarding** streams every audit event to your own SIEM
in real time, independently of the periodic exports above - useful when
security already lives in a central log platform and shouldn't require
someone to remember to run an export.

### Adding a forwarder [#adding-a-forwarder]

Click the add button and pick a **type**:

| Type    | Transport                                                | Format            | Typical target                                         |
| ------- | -------------------------------------------------------- | ----------------- | ------------------------------------------------------ |
| Webhook | HTTPS POST                                               | JSON, HMAC-signed | Splunk HEC, Microsoft Sentinel, any HTTP log collector |
| CEF     | TCP, optional TLS (default port 514)                     | ArcSight CEF line | ArcSight / classic CEF collectors                      |
| Syslog  | TCP, optional TLS (default port 6514, TLS on by default) | RFC5424 line      | rsyslog, syslog-ng, or any generic syslog SIEM         |

For webhook, the endpoint field is a full `https://` URL. For CEF/syslog,
it's `host:port`. An optional HMAC secret on a webhook forwarder signs
every POST with the same `X-Orboto-Signature: sha256=<hex>` scheme used
by regular [webhooks](/admin/data/webhooks) - verify it on your
collector by recomputing the HMAC over the exact bytes received. The
secret itself is never returned by the API once saved (the form shows
only whether one is set); leaving it blank while editing keeps the
existing one.

### Before you rely on it: test-send [#before-you-rely-on-it-test-send]

Every forwarder has a **test-send** button (the paper-plane icon) that
delivers a synthetic `siem.forwarder.test` event through the exact same
delivery path a real event would take - use it right after saving a new
forwarder to confirm connectivity and correct parsing on the receiving
end before flipping it on for real traffic.

### Delivery behavior [#delivery-behavior]

* Forwarding is fully decoupled from whatever action produced the audit
  event: the event is written to the audit log first, then handed off to
  the forwarding queue - a slow or completely offline SIEM never slows
  down or blocks the action that triggered it.
* Each (event, forwarder) pair retries with backoff, up to five attempts.
  A forwarder that already succeeded for a given event is skipped on any
  later retry pass, so retries can never double-deliver the same event.
* After the retry budget is exhausted, the attempt is recorded as
  `dead_letter` rather than silently disappearing.
* Expand any forwarder row to see its **delivery log**: every attempt
  with its outcome (success / failed / dead-letter), the attempt count,
  and the last error - the place to look when "is my SIEM actually
  getting everything?" needs a real answer instead of a guess.
* **Toggle** (enable/disable) and **Edit** work on any forwarder;
  **Delete** removes it and stops all further deliveries permanently.

### Payload shapes [#payload-shapes]

Webhook JSON body (inside no extra envelope - this IS the body):

```json
{
  "id": "<audit row uuid>",
  "timestamp": "2026-06-20T10:00:00.000Z",
  "action": "ticket.updated",
  "actor": { "id": "<uuid|null>", "email": "alex@example.com" },
  "entity": { "type": "ticket", "id": "ACME-42" },
  "details": {},
  "source": "orboto"
}
```

CEF line shape: `CEF:0|orboto|orboto|<version>|<action>|<action>|3|<extensions>`,
where the extensions carry `rt` (event time, epoch ms), `suser`/`suid`
(actor email/id), `cs1`/`cs2` (entity type/id labeled `entityType`/
`entityId`), and `externalId` (the audit row id). Severity is always `3`.

Syslog uses `PRI 134` (facility `local0`, severity `info`); the actor and
entity ride in RFC5424 STRUCTURED-DATA under the `orboto@0` SD-ID, with
the full JSON event as the message body.

This is an Enterprise capability - it works on every tier with a
soft-warn note on the License page rather than being blocked, so you can
try it before deciding to upgrade.

## Troubleshooting [#troubleshooting]

* **A signed export won't verify with the offline verifier** - re-download
  it first; a partial or corrupted download breaks the hash chain the
  verifier checks. If a clean re-download still fails, treat it as a
  genuine tamper signal and cross-check against a live **Verify integrity**
  run on the same date range from the [audit chain page](/admin/operations/audit-and-compliance).
* **SIEM forwarder shows repeated dead-letters** - test-send first to
  rule out a bad endpoint or wrong port (CEF defaults to 514, syslog to
  6514\); check the forwarder's delivery log for the last error, which
  usually points straight at a TLS handshake or authentication failure
  at the collector.
* **Webhook forwarder's HMAC never matches on the receiving end** - sign
  over the *raw* bytes received, exactly as the webhooks doc describes;
  the same trap applies here as for regular webhooks.
* **An export generation seems stuck** - large date ranges genuinely take
  time to build; check the History table's status before assuming it
  failed. If it's been stuck at "generating" far longer than the range
  would justify, retry with a narrower date range.


# Data protection (GDPR) (/admin/operations/data-protection)



**Admin -> Compliance** is where GDPR obligations toward individual
people (as opposed to the audit-trail evidence covered elsewhere) get
tracked and enforced. Three cards, each self-gating on its own
permission so you only see what you're allowed to act on.

## Data-subject requests (DSAR) [#data-subject-requests-dsar]

{/* screenshot: Admin - Compliance page, DSAR card with a logged request row */}

Track every GDPR data-subject request - Art. 15 (access), Art. 16
(rectification), Art. 17 (erasure), Art. 20 (portability) - from intake
to an auditable closure, instead of handling them ad hoc over email.

**Logging a new request:**

1. Pick the **request type** from the dropdown (Access / Rectification /
   Erasure / Portability).
2. Enter the **data-subject's email** (required).
3. Optionally, the **linked user UUID** - if the request is about
   someone who has (or had) an orboto account, filling this in is what
   lets the **Export** and **Anonymize** action buttons work directly
   from this request; without it, you can still track the request but
   have to handle the actual data action outside this card.
4. Optionally, a **due date** - your own statutory-deadline tracker, not
   enforced by orboto itself, just displayed so nothing falls through.
5. Click **Log request**.

**Working a logged request** - each row shows its type, status, and
whatever actions your permissions allow:

* **Export** (needs the DSGVO-export permission) - runs the same
  machine-readable personal-data export used elsewhere, tied to this
  request for the audit trail.
* **Anonymize** (needs the DSGVO-anonymize permission) - a browser
  prompt requires you to type `ANONYMIZE` before it runs; this is
  irreversible, so the request card requires a deliberate typed
  confirmation rather than a single click.
* **Rectify** - prompts for a short description of the correction made
  (for the Art. 16 record); it doesn't perform the edit itself, it
  records that a correction was made and what it was, since
  rectification usually means editing a specific field somewhere else in
  the product.
* **Close** - marks the request **Completed** or **Rejected**, with an
  optional closure note. This is the step that makes the request
  auditable end-to-end: intake, the action taken, and a recorded outcome.

Status values you'll see: **Open** (just logged), **In progress**,
**Awaiting subject** (you're waiting on the person themselves for
something), **Completed**, or **Rejected**.

Both **Export** and **Anonymize**, whether triggered from a DSAR request
or run standalone elsewhere in the admin panel, are themselves
audit-logged - the DSAR record and the audit log corroborate each other.

## Legal holds [#legal-holds]

A legal hold **preserves** a project, a user, or a ticket against
deletion and retention - once held, that scope cannot be hard-deleted or
anonymized (including via the retention policy below) until the hold is
explicitly released.

To place one: pick the **scope type** (Project / User / Ticket), paste
the specific **scope UUID**, enter a **reason** (e.g. "litigation",
"active investigation" - required, shown in the hold list so anyone
looking at it later understands why), and click **Place hold**. Active
holds list below with their scope, truncated id, and reason; click
**Release** on any of them once the hold is no longer needed - release is
immediate and simple (no typed confirmation), since releasing a hold
doesn't delete anything itself, it just re-exposes that scope to normal
deletion/retention rules going forward.

## Data retention [#data-retention]

Configure automatic cleanup of old data past a configured age, in three
independent fields (each in days; **0 means keep forever** for that
category):

* **Closed tickets older than (days)**
* **Audit log older than (days)**
* **Notifications older than (days)**

The retention job runs daily. Anything covered by an active **legal
hold** above is never purged, regardless of its age against these
settings - the hold always wins.

## Troubleshooting [#troubleshooting]

* **Export/Anonymize buttons don't appear on a DSAR request** - either
  the request has no linked user UUID (fill it in via edit, if the
  request wasn't originally logged with one, or handle the data action
  manually outside this card), or your own account lacks the specific
  `admin:dsgvo:export` / `admin:dsgvo:anonymize` permission even though
  you can see and log requests generally.
* **Anonymize prompt won't accept your input** - the confirmation is
  case-sensitive and must be typed exactly `ANONYMIZE`, not a
  translation or a close variant.
* **A user/project/ticket won't delete or anonymize even though nothing
  looks unusual about it** - check for an active legal hold on that exact
  scope UUID; a hold blocks the action silently from the requester's
  point of view unless they know to look here.
* **Retention doesn't seem to be purging anything** - confirm the
  relevant field isn't set to `0` (which means keep forever for that
  category by design, not a bug), and remember it runs once daily, not
  immediately after you save the setting.
* **A DSAR request's due date passed with no action** - resolve it via
  the appropriate action (export/anonymize/rectify) and **Close** it with
  the outcome recorded; an auditor reviewing your DSAR handling will look
  for the closure trail, not just that the request exists.


# Federation conflicts and user mapping (/admin/operations/federation-conflicts)



Once a federation link or a project pair is syncing (see
[Federation](/admin/operations/federation)), two things need
ongoing admin attention: identities that arrive from the peer without a
matching local account, and edits that happened on both sides close
enough together that one had to lose. Both surfaces live under
**Admin -> Federation**, reachable from the buttons at the top of that
page.

## Federated ghost users [#federated-ghost-users]

{/* screenshot: Admin - Federation - Ghost users page, list with "Merge into..." */}

When a synced event names a user your instance has never seen - the
author of a comment, the assignee of a ticket - orboto can't just drop
the attribution, so it auto-creates a lightweight **ghost user**: a
placeholder account with the peer's name and email, no password, no
sign-in. This keeps every comment and time entry correctly attributed
from the moment it arrives, instead of showing "unknown user" or silently
reassigning it to whoever happened to run the sync.

**Admin -> Federation -> Ghost users** lists every ghost currently on
your instance: its generated name, the remote email it came from, and
when it was created. For each one:

1. Click &#x2A;*Merge into...**.
2. Search for the real local user by name or email (type at least two
   characters to search).
3. Pick them from the results list.
4. Click **Merge**.

The merge rewrites every row the ghost owned onto the real user - a
confirmation toast reports exactly how many of each: comments, time
entries, ticket assignments, ticket-access ACL rows, project
memberships, and the internal sync-user mapping (so future events from
that same remote person resolve straight to the real account, no new
ghost created). The ghost account itself is deleted once the rewrite
completes.

**When to merge:** as soon as you recognize who a ghost actually is - a
subcontractor who also has a real seat on your instance, a partner
company's employee you're now collaborating with more directly. There's
no downside to leaving a ghost unmerged (attribution stays correct
either way); merging just consolidates it into one account going
forward.

## Sync conflicts [#sync-conflicts]

{/* screenshot: Admin - Federation - Conflicts page, expanded conflict row with two payload panels */}

### What counts as a conflict [#what-counts-as-a-conflict]

Federation resolves concurrent edits with **last-write-wins by
timestamp**: when an incoming event's `updatedAt` is older than the
local row's own `updatedAt`, the incoming edit loses - your local copy
already had a newer change, so the incoming one is skipped rather than
overwriting it. That skip is what gets recorded as a conflict; nothing
is ever silently dropped - both the incoming and the local payload are
preserved for you to review.

### How often this should happen [#how-often-this-should-happen]

* **A one-way link (source -> target)** - essentially never; the
  consuming side never edits, so there's nothing for it to conflict
  with.
* **A bidirectional link or project pair, normal use** - a handful a
  week is unremarkable; usually two people editing the same ticket or
  comment on both sides within moments of each other.
* **After a network split or an extended peer outage** - a batch on
  reconnection as both sides' backlogs re-converge, tapering off quickly.
* **Dozens or more per day, sustained** - something is wrong; work
  through the checklist below rather than dismissing them one by one.

### Working the queue [#working-the-queue]

**Admin -> Federation -> Conflicts** lists conflicts filtered to
**Unresolved** by default. Filter further by link, by project federation
pair (once you have any), or by entity type (e.g. `ticket`). Click a row
to expand it and see both payloads side by side: the peer's version
(labeled "skipped", in amber, with its timestamp) and your local version
(labeled "kept", in green, with its own timestamp) - the raw JSON each
side held at the moment of the conflict.

For each unresolved row, decide:

* **Dismiss** - the two payloads are effectively the same content (a
  near-simultaneous edit that raced through the sync loop, or the
  meaningful fields already match). No action needed; marks the row
  resolved with no data change.
* **Use peer's version** (re-apply) - the incoming payload should have
  won - the remote side is the canonical source for this data, or its
  edit was actually the more complete/correct one. This overwrites your
  local row with the peer's payload and marks the row resolved.
* Neither fits cleanly (each side has a piece of the right answer) - edit
  the local row by hand to the state you actually want, then **Dismiss**
  the conflict (the manual edit is now the record; dismissing just closes
  the queue item).

A resolved row stays visible under the **Resolved** or **All** filter
with its resolution shown, for later audit.

### Preventing conflicts in the first place [#preventing-conflicts-in-the-first-place]

* On a **bidirectional link**, agree a simple rule with the other side:
  edits to a given shared ticket happen on ONE side at a time when
  possible. Keep both hosts' clocks tightly NTP-synced - skewed clocks
  can make a genuinely correct, later edit look older than it was and
  lose a conflict it should have won.
* For a ticket you know is about to be touched on both sides at once,
  use orboto's realtime in-instance updates (if both people are on the
  same instance) or just say so in chat first - federation replication
  has the link's poll-interval latency, it isn't instant.
* If one side is authoritative in practice more often than not, consider
  switching that link from `bidirectional` to `source`/`target` -
  demoting concurrent edits from "occasional silent loss to review"
  into "a workflow rule that's enforced by the system", which is easier
  to reason about at scale.

## Troubleshooting [#troubleshooting]

* **A conflict keeps reappearing for the same ticket** - both sides are
  likely still actively editing it around the same time on every sync
  cycle; agree who edits it going forward, or temporarily pause the link
  while you coordinate the change together.
* **Sudden spike in conflicts across many entities at once** - check NTP
  sync on both hosts first; a clock that jumped (VM resume, manual
  change) can make every subsequent conflict decision wrong until it's
  corrected. The second most common cause is a bulk import running on
  one side while the other stayed live and editable - pause the link
  during large imports if this keeps recurring.
* **"Use peer's version" doesn't seem to have taken effect** - the mask
  or entity scope on the link may be excluding the field you expected to
  change; re-apply overwrites what the sync pipeline is allowed to carry,
  not fields that never cross at all.
* **A ghost user's merge target search finds nobody** - search matches by
  name or email; if the real account uses a different email than the one
  the remote side sent, search by name instead, or check the account
  actually exists on this instance yet.


# Federation (/admin/operations/federation)



Federation connects **separate orboto instances** - for example your
production workspace and a partner company's own orboto - and keeps
shared ticket/project data flowing between them automatically. Each side
keeps its own users, permissions and infrastructure; only the federated
data crosses the wire. This is an Enterprise capability with two distinct
modes that solve different problems - pick the one that matches what you
actually need before setting anything up.

|                    | Instance federation                                          | Project federation                                                                       |
| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Who sets it up     | A workspace admin, on both sides                             | A project owner on the sharing side; a workspace admin accepts on the receiving side     |
| Where              | Admin -> Federation                                          | Project Settings -> Federation (invite side); the API, on the accepting side - see below |
| Scope              | The whole instance, or a filtered subset of its projects     | Exactly one project, shared with exactly one partner instance                            |
| Bootstrap          | An admin manually exchanges URLs, tokens and a shared secret | The owner mints a time-limited invite link/QR code; the partner pastes it in once        |
| What can be shared | Any of 18 entity types, symmetric per link                   | Field-level masks, independently configurable per direction                              |
| Mental model       | A replica or mirror of (part of) your workspace              | A shared folder for one project                                                          |

Use **instance federation** for a staging replica of production, a
regional office that should see (and maybe edit) the same data, or an
agency that runs client work inside its own instance. Use **project
federation** when you want to hand ONE project to an outside party -
a client, a subcontractor, your accountant - without exposing anything
else in your workspace, and without them needing an account on your
instance at all.

## How the two instances trust each other (security model) [#how-the-two-instances-trust-each-other-security-model]

Every request one peer sends to the other must pass three independent
checks, all enforced server-side, before any data moves:

1. **Bearer token.** The caller sends `Authorization: Bearer <token>`.
   The receiving side hashes it and compares against the stored hash for
   that link - only the hash is ever stored, never the plaintext, so a
   database leak on either side doesn't hand over live credentials.
2. **Timestamp freshness.** The request carries a timestamp header that
   must be within five minutes of the receiving server's clock. This
   blocks replay of an old, captured request.
3. **HMAC signature.** The request is signed over `<timestamp>.<raw body>`
   using a **shared secret** both sides hold in plaintext (needed to sign
   outbound requests too). The receiver recomputes the signature and
   compares it.

All three must pass or the request is rejected with a single, deliberately
generic error - the response never reveals *which* check failed, so a
probing attacker learns nothing useful from a failed attempt. Every
successful and failed credential check, link creation, rotation, and
conflict decision is written to the audit log with the acting admin's id,
so `Admin -> Audit log` is your source of truth after an incident.

Federated data itself is **never** re-authenticated per user on the
sending side beyond the link/pair check above - once a link or a project
pair is set up, it moves whatever its scope and masks allow. This is why
narrowing scope (instance federation) or picking a tight preset (project
federation) matters: the link IS the trust boundary.

## Instance federation - step-by-step setup [#instance-federation---step-by-step-setup]

{/* screenshot: Admin - Federation page, empty state and "Add link" button */}

This walks through connecting two instances - call them **A** (where you
start) and **B** (the peer). The steps are identical regardless of
direction; only the values differ.

### 1. Decide the direction upfront [#1-decide-the-direction-upfront]

* **Source** - A emits changes, B (or a fleet of consumers) reads them. A
  never applies anything B sends. Use this for a one-way mirror, e.g.
  production feeding a read-only staging replica.
* **Target** - A only consumes from B; B is authoritative. The mirror
  image of Source.
* **Bidirectional** - both sides emit and consume. Use this for two
  offices that both actively edit shared projects.

### 2. On instance A: create the link [#2-on-instance-a-create-the-link]

Go to **Admin -> Federation -> Add link** and fill in:

* **Link name** - a label for your own reference (e.g. "Stage mirror").
* **Remote URL** - B's base URL, e.g. `https://orboto.partner.example.tld`.
  Must be HTTPS.
* **Direction** - as decided above, from A's point of view.
* **Poll interval** - how often A pulls from B (only meaningful for
  `target` / `bidirectional`, since a `source` link never pulls). Default
  60 seconds, minimum 15, maximum 3600. Leave the peer's bearer token
  field blank for now.
* **Entity scope** and **project filter** - see "Narrowing what syncs"
  below. Leave both empty on a first setup; you can tighten them later.

Click **Create link**. A modal shows, **once**, the credentials A just
generated for B to use:

* **Incoming token** - B will send this in `Authorization: Bearer …` when
  it talks to A. A stores only its hash.
* **Shared secret** - both sides use this to sign every request.

Copy both immediately and check the "I've saved these values" box before
closing - there is no way to retrieve them again; only rotation produces
a new one.

### 3. On instance B: create the matching link [#3-on-instance-b-create-the-matching-link]

Log into B's own Admin -> Federation and create a link the same way, but:

* **Direction** is the mirror of A's - if A picked `source`, B picks
  `target`; if A picked `bidirectional`, B also picks `bidirectional`.
* Paste the **shared secret** A generated into B's link (the field is
  editable at creation).
* Leave B's own generated **incoming token** to copy afterward - A will
  need it.

### 4. Cross-paste the tokens [#4-cross-paste-the-tokens]

* On A's link (Edit), paste B's incoming token into "Peer's bearer
  token".
* On B's link (Edit), paste A's incoming token into "Peer's bearer
  token", if you hadn't already.

At this point each side holds: its own incoming token (hash only), the
peer's incoming token (used as the outgoing token, encrypted at rest),
and the same shared secret in plaintext on both sides.

### 5. Let it sync, or dry-run it first [#5-let-it-sync-or-dry-run-it-first]

Nothing more to configure - the scheduler picks up new/changed links on
its next tick (within a minute). Watch the link card: the health dot goes
amber ("Pending first sync") then green ("Healthy") once a poll succeeds,
and "Last polled" stamps with the latest attempt.

For a cautious first run, toggle **Dry-run: on** on the link before that
first poll. Events are fetched and logged but never applied or
acknowledged - safe to inspect, nothing changes. Toggle it back off once
you're satisfied.

### Narrowing what syncs [#narrowing-what-syncs]

* **Entity scope** - check only the entity types this link should carry
  (project, milestone, label, version, ticket status, ticket, ticket
  assignment, ticket label, ticket ACL, ticket dependency, comment, time
  entry, project member, doc space, doc, doc revision, attachment,
  project template). Leave every box unchecked to sync everything the
  direction allows.
* **Project filter** - check specific projects to restrict sync to just
  those; leave empty to sync every project the scope permits.

### Managing a link day to day [#managing-a-link-day-to-day]

Each link card offers, inline: **Pause/Resume** (stop and restart syncing
without losing configuration or history), **Dry-run** toggle, **Rotate
token** (invalidates the old incoming token immediately - the peer needs
the new one before its next poll or it 401s), **Rotate secret** (the peer
must mirror the new value within minutes or every signature check starts
failing), **Edit** (change name, URL, direction, poll interval, scope,
filter), **Force-resync** (target/bidirectional links only - replays
every event the peer still has; unchanged rows are harmless no-ops, rows
that drifted apart surface as new conflicts to triage), and **Delete**
(removes the link, its sync history and any open conflicts for it; data
already mirrored locally is not rolled back).

## Project federation - step-by-step setup [#project-federation---step-by-step-setup]

Use this to share exactly one project without wiring up whole-instance
federation. It has an intentionally different flow: the project owner
initiates, and it never touches Admin -> Federation's link plumbing
directly (those links exist under the hood but are invite-managed).

### 1. On your side: create the invite [#1-on-your-side-create-the-invite]

Open the project, go to **Project Settings -> Federation**
(`project:federation:manage`, granted to project admins by default - no
workspace-level federation permission needed here) and click **Invite
partner instance**. Pick a sharing preset (see the table below), add an
optional note the accepting admin will see, and click **Create invite**.
You get a **token** (with a copy button) and a **QR code**, both valid for
**15 minutes**. Send either to the partner's admin through whatever
channel you'd use to share a link with them.

### 2. On the partner's side: accept the invite [#2-on-the-partners-side-accept-the-invite]

The partner's workspace admin (needs `admin:federation:write`) accepts
the invite by calling the API directly - `POST
/federation/accept-project-invite` with the token - since there is
currently no dedicated admin-panel page for this step. Once accepted, the
project federation shows up on both sides.

### 3. Watch it sync [#3-watch-it-sync]

Project pairs poll roughly every **15 seconds** (faster than the 60-second
instance-link default, since partner comments should feel conversational,
not batched). The federation card on your Project Settings -> Federation
tab shows a health dot: &#x2A;*amber "pending"** until the first poll
succeeds, &#x2A;*green "active"** once it has, &#x2A;*grey "paused"** if you've
paused it, &#x2A;*red "error"** if the last poll failed (hover the dot for the
reason). A small globe marker appears next to the project name on both
sides once it's live.

### Sharing presets [#sharing-presets]

{/* screenshot: Project Settings - Federation, invite dialog with preset radio buttons */}

| Preset                    | Tickets                                                                     | Milestones/Labels/Versions/Statuses | Dependencies | Comments    | Time entries        | Docs        | Attachments | Fields stripped                    |
| ------------------------- | --------------------------------------------------------------------------- | ----------------------------------- | ------------ | ----------- | ------------------- | ----------- | ----------- | ---------------------------------- |
| Read-only view (default)  | yes                                                                         | yes                                 | yes          | no          | no                  | no          | no          | ticket description, estimated time |
| Comments and descriptions | yes                                                                         | yes                                 | yes          | public only | no                  | no          | no          | estimated time                     |
| Full collaboration        | yes                                                                         | yes                                 | yes          | public only | yes (no cost field) | public only | yes         | none                               |
| Custom                    | starts from Full collaboration, then tuned per direction in the mask editor |                                     |              |             |                     |             |             |                                    |

Assignees only cross on Full collaboration or Custom. A preset is applied
symmetrically at invite/accept time and can be re-tuned independently per
side afterward.

### Managing an active project federation [#managing-an-active-project-federation]

* **Edit sharing masks** (the slider icon) opens a mask editor: which
  entity types sync at all, and two free-form lists - **fields we do not
  send** (outbound) and **fields we do not accept** (inbound) - letting
  you strip specific fields (e.g. `ticket: estimatedTimeMinutes`) per
  direction independently. Saving flips the pair to the **Custom**
  preset. Changes apply to future events only - data already sent stays
  on the peer.
* **Pause/Resume** stops sync without losing the pairing.
* **Revoke** requires typing the project's key to confirm (the same bar
  as the destructive backup-wipe flow). It deletes the pair and its
  underlying link; sync stops immediately on both sides. Data already
  synced is not clawed back - if that matters, this is a legal
  conversation with the partner, not a technical undo.
* **Open invites** (below the active list) shows invites created but not
  yet accepted, with a countdown; **revoke** on an open invite kills the
  token immediately even before it expires.

### Hardwired exclusions - never cross, regardless of any mask [#hardwired-exclusions---never-cross-regardless-of-any-mask]

Masks only narrow what's shared, they never widen it. The following never
cross a project federation pair no matter how you configure it: internal
comments, private tickets, private milestones, non-public docs, ticket
access-control rows, project-membership rows, password hashes, hourly
rates, time-entry cost, and project/milestone budget fields. Admin roles
and system configuration are not federatable data types at all.

## Troubleshooting [#troubleshooting]

* **Every poll 401s** - almost always a token rotation on one side that
  wasn't mirrored on the other. Re-paste both sides' current tokens.
* **"Direction mismatch" (403)** - the peer is pulling from a link you
  configured as `target` (you consume, they shouldn't be pulling from
  you). Fix the direction on one side to match reality.
* **Link stuck on amber "pending first sync" for more than a few
  minutes** - check the link card's inline error; usually the peer URL
  isn't reachable from your instance yet (DNS, firewall, or a typo in the
  base URL).
* **A project federation's health dot is red** - hover it for the last
  error; most commonly the peer instance is offline or its own link was
  revoked/rotated without telling you.
* **A field you expected to be shared isn't showing on the partner's
  side** - check the hardwired-exclusions list first (some things never
  cross, no matter what), then the pair's current mask - changing a mask
  only affects events from that point forward.
* **Federation between two orboto versions behaves oddly** - both
  instances need to run the same major version; cross-version event
  schema drift isn't supported.

For ghost-user identity mapping and resolving sync conflicts, see
[Federation conflicts and user mapping](/admin/operations/federation-conflicts).


# Licensing (/admin/operations/licensing)



orboto's core is free to self-host. Some capabilities are part of the
Business or Enterprise editions - the relevant admin pages state this
where it applies (for example SAML SSO and SCIM provisioning, SIEM
forwarding, and multi-instance federation).

## Entering a subscription key [#entering-a-subscription-key]

**Admin -> License** shows the current edition and accepts a subscription
key (format `OBO-XXXX-XXXX-XXXX-XXXX`). Features unlock immediately on
activation. The page also shows seat usage against your plan's cap, the
key's issue and expiry dates, and the list of features included with the
active plan.

**Re-verify now** re-checks the license against orboto's licensing
service on demand; **Reload** re-reads the currently stored license
without a network round-trip; **Disconnect subscription** removes the
license and falls back to Community immediately.

## Grace period [#grace-period]

If a subscription expires, the workspace enters a grace period rather
than hard-stopping mid-sprint - the plan's features stay available until
the grace period ends, after which the workspace falls back to Community.

## Air-gapped activation [#air-gapped-activation]

An **Air-gapped** tab on the License page accepts an offline license file
for installations with no outbound network access to orboto's licensing
service, instead of the online key-activation flow.

## Feature usage tracking [#feature-usage-tracking]

Business/Enterprise-gated features that are used on the Community plan
(a "soft-warn" posture - the feature works, a banner notes the tier) are
logged here: which feature, how many times, first and last use. This is
informational only.


# System settings (/admin/operations/system-settings)



**Admin -> System settings** holds every workspace-wide configuration
key that isn't specific to AI (that has its own page - see
[AI providers and models](/admin/ai/ai)). The page renders as a
series of cards, one per group; every field saves individually as you
change it - there's no separate "Save all" step, so a field takes effect
the moment you commit it (press Enter or click away for a text field,
immediately for a checkbox or dropdown).

## General [#general]

* **Workspace name** and **Logo URL** - shown in the app header and
  browser tab title everywhere in the workspace.
* **Workspace language** - the language content is expected to be
  written in. This single setting drives the auto-translate and
  strict-language guardrails documented in full on
  [Translations](/admin/operations/translations) - set it once here
  before turning either of those on.
* **Workspace timezone** - the sole authority for **when** scheduled jobs
  fire: backups, retention cleanup, digests, alerts. Type a real IANA
  zone name (e.g. `Europe/Berlin`) - a suggestion list appears as you
  type, and the field shows the current time in that zone right below it
  once you've entered a valid one, so you can visually confirm you typed
  the zone you meant. This is completely separate from each user's own
  **display** timezone in their Profile, which only affects what time
  they see on screen, never when anything actually runs.
* **Allow self-registration** - on by default. Off requires every new
  user to be invited rather than signing up on their own.
* **Allowed email domains** - a comma-separated allowlist (e.g.
  `acme.com, partner.org`); leave empty to allow any domain to
  self-register when self-registration is on.
* **Default currency** - the ISO-4217 code (EUR, USD, GBP, and others)
  used for any newly created project; a project that already exists
  keeps whatever currency it was created with, changing this default
  never retroactively changes existing projects.
* **Presence indicators** - the online/invisible status dot shown on
  avatars throughout the app. Turning this off hides every presence
  surface workspace-wide instantly; the underlying presence data isn't
  deleted, so turning it back on later shows correct state again rather
  than starting from scratch.
* **Send welcome email on registration** - on by default; fires once per
  new account (self-registration or invitation-redeem). This toggle
  ONLY controls whether the email fires at all - to change its subject or
  body, use the Email Template Editor's "Welcome" template, not this
  page.
* **Block duplicate tickets at similarity** - a number from 0 to 1 (or
  empty). At 0/empty, a near-duplicate ticket only gets an advisory
  warning when created. Set it above 0 (0.90 is the recommended starting
  point, corresponding to a "high-similarity match") to have orboto
  outright refuse creating a ticket whose closest existing match scores
  at or above that similarity - the creator (or an agent) has to
  deliberately override with a stated justification to push through
  anyway. This check is automatically skipped while a project is in the
  middle of a rapid create-burst (a bulk import, for example), so it
  never blocks legitimate bulk work.
* **Require MCP agents to load the rules first** - off by default. When
  on, any AI client connected via MCP must call the session-start tool
  (which returns this workspace's binding operating rules) before any
  other MCP tool call is allowed to run in that session - the very first
  non-session-start call gets refused with an instruction telling the
  agent what to do instead. This guarantees every agent actually sees
  your rules at least once per session, at the cost of one extra call per
  connection.
* **Self-service agent accounts per user** - how many bot accounts one
  human user is allowed to create for themselves via the OAuth "Act as"
  picker on the consent screen. `-1` means unlimited, `0` turns
  self-service creation off entirely (only an admin can create bot
  accounts, under Admin -> Users), and leaving it empty defaults to `1`.
  This cap only counts a user's own self-created, currently-active bots -
  bots an admin created directly are never counted against it.
* **Maintenance mode** - off by default. Turning it ON asks for an extra
  confirmation click first ("Enable maintenance mode? Everyone except
  super-admins is locked out..."), since it's disruptive: every request
  from a non-super-admin gets a 503 with a maintenance page instead of
  the normal app, until you turn it back off (which is instant, no
  confirmation needed). Use it for a migration window or to contain an
  incident. Every toggle - on and off - is written to the audit log.

## Email delivery [#email-delivery]

Pick a **provider** from the dropdown: **Disabled** (no outbound email at
all), **orboto Mail Service** (recommended - EU-hosted, connects via
OAuth to your account at account.orboto.io/mail, auto-DKIM on `*.orbo.to`
subdomains, billing rolled into your orboto subscription), **Resend**
(a third-party API), or **SMTP** (your own existing mail server).
Choosing a provider reveals only that provider's own fields:

* **orboto Mail Service** - either click the **Connect** button below
  (OAuth flow, no manual key entry) or paste an API key (starts with
  `oms_`) directly, plus the verified **From address** and an optional
  base-URL override for self-hosted/staging use.
* **Resend** - an API key from resend.com/api-keys (starts with `re_`)
  and a From address using a domain you've verified in Resend.
* **SMTP** - host, port, username, password, and From address for your
  own mail server.

Whichever provider is active, a **Send test email** box at the bottom of
this card lets you type any address and fire a real test message through
the exact live configuration - do this after any change before assuming
delivery works, since a saved-but-wrong credential otherwise fails
silently until the first real notification tries to go out.

## Projects [#projects]

* **Enable RACI on new projects** - off by default. RACI (Responsible /
  Accountable / Consulted / Informed roles on tickets) stays opt-in per
  project either way; this only decides whether it starts pre-enabled on
  a brand-new project instead of the project owner having to turn it on
  themselves. AI agents also won't proactively suggest RACI assignments
  on a project where it isn't enabled.
* **Team availability (free/busy)** - who can see a teammate's near-term
  workload as a badge in the assignee picker: **Disabled** (default -
  nobody but admins), **Shared-project members only** (you see it for
  people you share at least one project with), or **All users**.
  Individual users can additionally opt themselves out in their own
  profile regardless of this workspace-wide setting.

## Workforce cost [#workforce-cost]

These three fields feed the "loaded member cost" analytics report and
nothing else - they don't gate or change any other behavior:

* **Overhead factor** - a multiplier applied on top of a member's hourly
  rate to approximate their fully-loaded cost to the business (benefits,
  office overhead, etc). `1.3` models a 30% markup over their raw rate.
  Applies workspace-wide by default; an individual member's overhead can
  still be overridden per-person in Admin -> Users.
* **AI input token price** and **AI output token price** (per one million
  tokens, in the workspace currency) - lets the same cost report also
  attribute a dollar figure to each person's AI usage (their own calls,
  plus any bot accounts they own). Leave either at 0 or empty to exclude
  AI spend from that report entirely.

## Kill switches [#kill-switches]

* **MCP server** - a dedicated card further down this same page (below
  the grouped settings) turns off the entire Model Context Protocol
  surface for the whole workspace at once - useful for compliance,
  incident response, or a staged rollout of MCP access. Even with MCP on
  workspace-wide, an individual user still additionally needs their own
  MCP permission to actually use it.
* **Agent autonomy pause** - stops every AI agent's *self-directed* work
  workspace-wide in one click; work explicitly assigned to an agent by a
  human keeps running regardless. This switch deliberately does NOT live
  on this page - it's on
  [Agents administration](/admin/ai/agents), right next to the live
  view of which agents are currently active, since that's the more
  useful place to decide "should I hit pause right now."

## Other cards on this page [#other-cards-on-this-page]

Below the grouped settings, three standalone cards: **Report branding**
(toggle the "Generated with orboto.io" footer on exported documents -
removing it needs Business or Enterprise), **Telemetry** (opt out of the
anonymous usage beacon), and **Developer tools** (a self-service download
of the AI-agent skill package - the same download available from your
own Profile page, surfaced here too for an operator who wants a single
place to find everything an integrator might need).

## Delegation [#delegation]

Every settings area can be delegated without handing out full system
access. The clearest example: the AI provider keys on the
[AI settings](/admin/ai/ai) page are writable by anyone holding the
AI-admin permission alone, entirely independent of the general
`admin:system:write` permission this page's other fields need. The
general rule across all of orboto's admin surfaces: what a user cannot
change, they also do not see - a partial-access admin gets a genuinely
smaller page, not a full page with disabled controls.

## Troubleshooting [#troubleshooting]

* **Timezone save is rejected** - the value must be a real IANA zone name
  (`Europe/Berlin`, `America/New_York`), never an abbreviation like `CET`
  or a raw UTC offset; the error appears right under the field, and the
  "current time there" preview only shows once you've entered something
  valid.
* **Test email succeeds but real notifications still don't arrive** -
  confirm the provider selected is genuinely the one you configured;
  switching providers doesn't clear the other providers' now-stale
  fields, and the test always uses whichever provider is currently
  selected in the dropdown, so a stale selection can pass its own test
  while the real, intended provider never gets used.
* **A masked secret field looks empty after a page reload** - that's
  expected, not a bug: secrets never round-trip back into the form once
  saved. Leaving the field blank on your next save keeps the existing
  stored value; typing anything into it replaces it.
* **Maintenance mode locked out the last admin too** - only super-admins
  bypass the maintenance page; if no super-admin account exists on this
  instance, you'll need to disable it directly against the database or
  restore from a backup, since the UI itself sits behind the same gate
  for everyone else once it's on.
* **A change to "Enable RACI on new projects" didn't affect an existing
  project** - correct, by design; this setting only decides the default
  for brand-new projects going forward. Toggle RACI on an existing
  project from that project's own settings instead.


# Translations (/admin/operations/translations)



orboto's UI ships in multiple languages out of the box - each user picks
their own from a dropdown in their Profile, independent of anything on
this page. **Content** - ticket titles and descriptions, comments, docs -
is a separate concern: it can be machine-translated when it arrives in a
different language than the workspace expects, if an AI provider is
configured, and it feeds features that work best when content is
linguistically consistent.

## Why this matters [#why-this-matters]

orboto's search (full-text search with stemming and stopwords) and its
AI features (semantic search, duplicate detection, Ask-Docs) both assume
the workspace's content is written in one consistent language. A
workspace with tickets scattered across five languages doesn't just look
untidy - full-text search stops finding obvious matches because its
stemming rules are language-specific, and semantic-similarity comparisons
between a German ticket and its near-duplicate English twin are far
weaker than between two tickets in the same language. The controls on
this page exist to keep content uniform without forcing everyone who
writes a ticket to personally translate it first.

## Setting the expected language [#setting-the-expected-language]

**Admin -> System settings -> Workspace language** sets the language
content is expected to be written in. This drives three related
controls, all under System settings:

* **Auto-translate new tickets to workspace language** (off by default) -
  when a new ticket is written in a different language, orboto translates
  the title and description via the configured AI provider and keeps the
  original text as a comment, so nothing is lost. Requires AI to be
  configured; without it, mismatched tickets are only flagged with a
  warning, not translated.
* **Reject tickets not written in the workspace language** (off by
  default) - when on, a create/update whose detected language differs is
  blocked (422) instead of just warned, unless the caller passes an
  explicit override. This is a guardrail an agent can override
  per-request with a reason, not a hard lock.
* Both interact: auto-translate resolves a mismatch before the strict
  guardrail would reject it, when both are on.

## The review workflow [#the-review-workflow]

{/* screenshot: Admin - Translation review page, pending queue */}

**Admin -> Translations** lists every ticket the auto-translate flow
rewrote, defaulting to the **pending** queue (all reviewed rows are still
visible under **All**). Each row shows the ticket, its translated title,
the source -> target locale pair, and review status. Per row:

* **Approve** marks the translation reviewed - it's already being served
  to users reading in the target language; approving just closes the
  review loop.
* **Revert** restores the original pre-translation content and removes
  the auto-translated marker - use it when the machine translation
  materially changed meaning or tone.
* **Open ticket** jumps straight to the ticket for full context.

Translations regenerate lazily: if the source text changes after
translation, the next request produces a fresh translation rather than
serving a stale one - so an edited ticket's translation catches up
automatically, no manual re-run needed.

## Troubleshooting [#troubleshooting]

* **Translations never appear even with auto-translate on** - confirm an
  AI provider is actually configured and reachable (Admin -> AI settings);
  auto-translate silently produces nothing without one, it does not error
  loudly on every affected ticket.
* **A ticket keeps getting flagged as the wrong language** - short,
  jargon-heavy text (a one-line title, mostly proper nouns or code) is
  where automatic language detection is least reliable. If this repeats
  across a batch (e.g. an import), it's worth reviewing whether that
  batch's content is actually the expected language before trusting the
  detector on it.
* **Strict enforcement is blocking legitimate mixed-language work** - an
  agent or integration can override per-request, but if this is a
  recurring, legitimate pattern (a support inbox that receives multiple
  languages by design), reconsider whether enforcement should be on for
  that workspace at all rather than fielding overrides constantly.
* **A reverted translation reappears** - if the source content hasn't
  changed, reverting is final; if it recurs, the ticket's content is
  probably being re-edited into the "wrong" language repeatedly - check
  who's editing it and in what language they're working.


# Attachments and storage (/admin/platform/attachments-storage)



Every file a user uploads in orboto - on a ticket, a doc, or a comment -
lands in object storage (S3-compatible; RustFS locally in development)
with a matching database row that tracks who uploaded it, its size, and
what it's attached to. **Admin -> Attachments** is the single
workspace-wide view across all of that, independent of digging through
individual tickets or docs one at a time.

## The attachments list [#the-attachments-list]

{/* screenshot: Admin - Attachments page, the table with the total size shown in the header */}

Each row shows the **filename** (with its content type), **size**,
**used in** - a link straight to the ticket, doc, or comment it's
attached to, with the parent project or doc space named alongside it -
**uploaded by**, and **uploaded at**. The header shows the **total
storage size** across every attachment currently in the workspace.

Filter by:

* **Filename search** - free text.
* **Type** - Tickets / Docs / Comments / all.
* **Orphaned only** - see below.

Delete any attachment with the trash icon; the confirmation wording
differs depending on whether the file is currently in use (deleting it
will visibly remove it from wherever it's attached) or already orphaned
(nothing else references it, so deleting it is pure cleanup).

## What "orphaned" means [#what-orphaned-means]

An attachment becomes **orphaned** when the database row that recorded
"this file belongs to that ticket/doc/comment" is gone, but the
underlying object in storage never got cleaned up alongside it - most
commonly the parent ticket, doc, or comment was deleted through a path
that didn't (or couldn't, due to a partial failure) also remove the
file. An orphaned row still shows up in this table (with an amber
warning badge instead of a working "used in" link) but represents
storage you're paying for with nothing in the product actually pointing
to it.

Toggle **orphaned only** to see just these - useful for a periodic
cleanup pass, or right after a data-import that may have left stray
references behind.

## Orphaned storage: objects with no database row at all [#orphaned-storage-objects-with-no-database-row-at-all]

A second, more subtle category exists one level deeper: **storage
objects** in your S3-compatible bucket that have **no attachment row
whatsoever** - not even an orphaned one. This can happen from an upload
that completed in storage but failed to record its database row (a
partial failure mid-request), or from an interrupted delete that removed
the row but not the object. When orboto detects any of these, a banner
appears at the top of the page reporting how many such objects exist and
their combined size.

{/* screenshot: Admin - Attachments page, the orphan-storage banner with the Reclaim now button */}

Click **Reclaim now** (with the confirmation naming exactly how many
objects will be removed) to delete every one of them from storage. This
action only ever touches objects that have zero database reference of
any kind - it can never remove a file something in the product still
points to, orphaned-row or not.

## Troubleshooting [#troubleshooting]

* **A file I deleted from a ticket still shows up here** - if it shows
  as orphaned (amber badge, no working link), the underlying storage
  object wasn't cleaned up when the reference was removed; delete it
  directly from this list to finish the cleanup.
* **The orphan-storage banner keeps reappearing after I reclaim** - a
  fresh interrupted upload or delete can create new orphaned objects at
  any time; this isn't a sign the reclaim itself failed, it's new
  orphans accumulating since the last pass. Check the reported count and
  size each time rather than assuming it should reach zero and stay
  there.
* **Total storage size doesn't match what I'd expect from active
  tickets/docs alone** - it's computed over every attachment row in the
  unfiltered set, including any orphaned rows still listed here; filter
  to **orphaned only** to see how much of the total that accounts for.
* **A delete failed** - the error message from the failed attempt is
  shown directly; a common cause is a storage-layer connectivity issue
  rather than anything about the specific file, so retry once storage is
  confirmed reachable.


# Background jobs (/admin/platform/background-jobs)



Not everything orboto does happens instantly while you wait for a page
to load. A lot of work - sending scheduled digests, pruning old data,
syncing with external systems, generating embeddings for search - runs
in the background on its own schedule. **Admin -> Background jobs**
gives you visibility into that layer: what's scheduled, when it last
ran, whether it succeeded, and a way to trigger a run on demand.

## What "a background job" means here [#what-a-background-job-means-here]

Behind the scenes, orboto runs a job queue (built on PostgreSQL) that
holds two kinds of work:

* **Scheduled (cron-driven) jobs** - things that run on a recurring
  timer regardless of what anyone does in the app: retention cleanup,
  digest emails, periodic sync polling, cache/session pruning, and
  similar housekeeping.
* **Event-driven jobs** - work enqueued in reaction to something that
  just happened (a ticket was created and needs an embedding generated,
  a webhook delivery needs to be attempted). These don't have a fixed
  schedule, but they still show up here once queued, with the same run
  history as scheduled jobs.

Every queue orboto knows about is listed on this page, whether or not
it has fired yet - so a brand-new workspace shows the full expected set
of jobs with empty history, not a shorter list that fills in over time.

## Reading the table [#reading-the-table]

{/* screenshot: Admin - Background jobs page, the job table with one row expanded showing run history */}

Each row is one job (queue), with:

* **Queue** - the internal job name.
* **Schedule** - its cron expression, or blank for an event-driven job
  with no fixed timer.
* **Last run** - a status badge: **completed**, **failed**, **active**
  (currently running), **cancelled**, or a dash if it's never run yet. A
  retry count appears next to the badge if the last run needed retries
  before finishing.
* **Last run time** - when that run started or completed, plus its
  error message inline underneath the row if it failed, so a failure is
  visible without opening the row.
* **Duration** - how long the last run took.
* **Next run** - when the job is next scheduled to fire (only
  meaningful for cron-driven jobs).
* **Actions** - a **Run now** button.

Click the row's expand arrow to see its **run history** - up to the last
50 runs, each with the same status/time/duration columns, plus a
**failed only** checkbox to filter straight to the runs that need
attention when a job has been flaky.

{/* screenshot: Admin - Background jobs page, expanded run history with the failed-only filter checked */}

## Run now [#run-now]

**Run now** enqueues a one-off execution of that job immediately,
bypassing its cron schedule entirely - it doesn't change or skip the
next scheduled run, it just adds an extra run right away. This is the
tool for two situations:

* You just changed a setting that job depends on (a retention threshold,
  a digest configuration) and want to see the effect immediately instead
  of waiting for the next scheduled window.
* A job failed and you've fixed the underlying cause (a misconfigured
  integration, a transient outage) and want to confirm the fix worked
  without waiting.

Some jobs accept no parameters and simply run their default behavior
when triggered this way (for example, the project-primer regeneration
job fans out to every project in the workspace in one click, rather than
needing a per-project manual trigger).

## Troubleshooting [#troubleshooting]

* **A job shows "failed" with no obvious cause** - expand the row and
  read the error message under **Run history**; it's the job's own
  thrown error, so it usually names the specific failure (a network
  timeout to an external system, a bad configuration value) rather than
  a generic failure.
* **Run now doesn't seem to do anything** - it enqueues the job; a busy
  queue may take a moment before the new run actually starts, and the
  page refreshes its status every 30 seconds, so a run that just started
  might not show as **active** until the next refresh.
* **Run now returns an error immediately** - the queue itself may not be
  running (for example in a degraded deployment state); this is
  reported distinctly from the job's own failures, since it means the
  job never even got the chance to start.
* **A job I expect to see isn't listed** - every queue orboto knows
  about is shown regardless of whether it has fired; if something is
  genuinely missing, it likely hasn't been wired into this admin view
  yet rather than being hidden - check with support before assuming it's
  silently failing.
* **Next run keeps slipping** - this only applies to cron-driven jobs;
  an event-driven job (queued in reaction to something happening
  elsewhere) has no fixed next-run time by design, since it only runs
  when there's actually something for it to do.


# Error log (/admin/platform/error-log)



**Admin -> Errors** is where crashes and exceptions from both the
orboto backend (API errors, 5xx responses, unhandled exceptions) and the
web frontend (JavaScript errors in the browser) land, grouped into
manageable **issues** instead of an endless list of raw events.

## Issues, not a raw event list [#issues-not-a-raw-event-list]

Two people hitting the same underlying bug shouldn't create two things
for you to look at - they should create **one issue** with a count of
two. orboto groups every error event by its **fingerprint** (roughly:
the same error type at the same code location) into an **issue**, and
the issue is what you triage, not the individual events. Each issue
tracks how many times it's happened, when it was first and last seen,
and a workflow status.

## Working the issue list [#working-the-issue-list]

{/* screenshot: Admin - Errors page, issue table with the filter bar and a status/escalation badge */}

The filter bar narrows what you're looking at:

* **Time window** - 1h / 24h / 7d / 30d.
* **Status** - unresolved (default) / resolved / ignored / all.
* **Free-text search** - matches an issue's title or culprit (the
  function or route where it originated).

Each row shows the issue's **status badge**, its title and culprit, how
many times it's occurred, and first/last-seen timestamps. Click a row to
open its **drill-in**: the same header info plus the individual events
that make up that issue, cursor-paginated so you can page through a
high-volume issue's full history.

### Per-issue actions [#per-issue-actions]

Available on both the list rows and the drill-in header (requires the
write permission - see below):

* **Resolve** - mark it fixed. New occurrences of the same fingerprint
  automatically **reopen** it, so a resolve doesn't have to be
  permanent if the underlying bug wasn't actually gone.
* **Ignore** - mark it as something you've deliberately decided not to
  act on (known noise, a third-party issue outside your control) without
  pretending it's "resolved." Ignored issues stay out of your default
  unresolved view but remain fully visible under the **ignored** filter.
* **Reopen** - move a resolved or ignored issue back to unresolved.
* **Escalate to developers** - send this issue's details to orboto's own
  developers via the product's telemetry channel, for cases where you
  believe you've hit a genuine product bug rather than something
  specific to your workspace's configuration or data. This is separate
  from any internal on-call or incident-response process you run - see
  [On-call and escalations](/admin/governance/on-call-and-escalations)
  for routing an incident to your **own** team instead.

{/* screenshot: Admin - Errors page, issue drill-in modal with the events list and the Resolve/Ignore/Escalate buttons */}

An escalation shows a state badge: &#x2A;*escalating...** while in flight,
**escalated** once sent, or **escalation failed** with the last error if
the send itself didn't go through (safe to retry).

## Look up a specific error by ID [#look-up-a-specific-error-by-id]

Separate from the issue-triage flow above: if a user reports an error
and hands you the short ID shown in orboto's own error UI (e.g. from a
toast or an error boundary screen), paste it into the **look up a
specific error by ID** box at the top of the page to jump straight to
that one event's full detail - independent of whatever time window or
status filter you currently have set on the issue list.

## Event detail [#event-detail]

Opening an individual event (from the drill-in list, the ID lookup, or
the live feed below) shows its full detail: the error message, an
expandable **stack trace**, an expandable **context** block (structured
metadata captured with the error - with a count of any fields that were
redacted before storage), which user hit it (if known), their IP
address, the route and HTTP status involved, and a request ID for
cross-referencing server logs.

Two convenience actions: **copy ID** (just the short error ID, handy for
asking a user "can you give me the ID from your error screen") and
**copy as Markdown report** (a ready-to-paste bug report with the
message, stack, context, and metadata formatted as Markdown - useful for
pasting straight into a ticket).

{/* screenshot: Admin - Errors page, single-event detail modal with the stack trace expanded */}

## Live tail [#live-tail]

Toggle **Live tail** to stream new error events as they happen, via a
persistent connection - useful while actively reproducing a bug or
watching a deployment roll out. A small floating panel in the corner
shows the last 10 events with a live/reconnecting indicator; click any
of them to open its full detail. This is a raw event stream (unaffected
by the issue grouping above, since new events arrive faster than they
can be grouped and displayed as issues), and your on/off preference
persists across visits to the page in your browser.

## Permissions [#permissions]

Reading the error log (the issue list, drill-ins, live tail, and ID
lookup) requires `admin:system:read`. The mutating actions - Resolve,
Ignore, Reopen, Escalate - require `admin:system:write`; without it you
see the same list and the same detail, just without the action buttons.

## Troubleshooting [#troubleshooting]

* **An error I know is happening isn't showing up** - check the time
  window filter first (it defaults to 24h, so anything older is hidden
  until you widen it), then the status filter (a previously-ignored
  fingerprint stays out of the unresolved view by default).
* **The same bug keeps creating separate issues instead of grouping** -
  fingerprinting groups by error type and code location; a bug that
  manifests through genuinely different code paths (different stack
  traces) is correctly treated as separate issues even if it "feels"
  like the same root cause to you.
* **A resolved issue reappeared on its own** - that's expected: a new
  occurrence of the same fingerprint automatically reopens a resolved
  issue, on the theory that if it happened again, it wasn't actually
  fixed.
* **Escalate to developers shows "escalation failed"** - this only
  means the send itself didn't go through (a network issue reaching
  orboto's telemetry endpoint); it's safe to retry, and it does not mean
  anything about the underlying error report was rejected.
* **Live tail shows "reconnecting" and nothing streams in** - the
  underlying connection dropped; toggling live tail off and back on
  re-establishes it. If it stays stuck, the issue list itself (with a
  manual refresh) is unaffected and remains reliable.


# MCP setup and usage (/admin/platform/mcp-usage)



This page covers the **admin** surfaces around orboto's [MCP
server](/agents-ai/mcp): onboarding another user, watching how much
MCP traffic your workspace generates, drilling into individual calls,
and switching MCP off workspace-wide if you ever need to. For how to
connect a specific AI client (Claude Desktop, Cursor, Copilot, Codex)
yourself, see [MCP server setup](/agents-ai/mcp) - this page is
about administering the surface other people connect to, not connecting
your own client.

## What MCP is, in one sentence [#what-mcp-is-in-one-sentence]

The [Model Context Protocol](https://modelcontextprotocol.io/) is a
standard way for AI clients to call structured tools against an
external system. orboto ships an MCP server so any MCP-aware AI client
can read and modify tickets, docs, milestones, and timers as a regular
orboto user - every call is authenticated and permission-checked exactly
as if that user had made the equivalent REST API call themselves.

## Onboard another user (Admin -> MCP setup) [#onboard-another-user-admin---mcp-setup]

Most people can set MCP up for themselves from their own **Profile**
page, but sometimes it's faster - or necessary, for a less technical
colleague or a bot account - for an admin to do it for them.

**Admin -> MCP setup** lets anyone holding `admin:mcp:write` mint an MCP
API key on behalf of another user and hand them a ready-to-paste client
configuration snippet. Pick the target user, pick which AI client
they're connecting (the snippet format differs by client), and pick a
delivery mode; the wizard generates the exact block they need to paste
into their client's configuration.

{/* screenshot: Admin - MCP setup wizard with the target-user and client pickers */}

A companion &#x2A;*"Set up with your coding agent"** card on the same page
covers the alternative bootstrap path for a user whose AI client can run
setup commands itself rather than needing a hand-pasted config snippet.

This page also previews the workspace's current **kill-switch state**
(below) before generating anything, so you see up front whether MCP is
even reachable for the account you're about to onboard.

## Usage dashboard (Admin -> MCP usage) [#usage-dashboard-admin---mcp-usage]

**Admin -> MCP usage** is the observability view: how much MCP traffic
is happening, who's generating it, and where errors or oversized
responses are showing up. It refreshes automatically every 30 seconds so
it's usable as a live view during an incident.

{/* screenshot: Admin - MCP usage page, KPI row and the daily volume bar chart */}

### KPI row [#kpi-row]

* **Calls (24h)** - total tool calls in the last day.
* **Active users (24h)** - distinct users who made at least one call.
* **Error rate (24h)** - percentage of calls that failed; highlighted
  once it crosses 5%.
* **p95 latency (24h)** - the 95th-percentile call duration, so a single
  slow outlier doesn't hide a system-wide slowdown (or vice versa).
* **Avg response size** - the average response payload size across
  calls, with a count of how many calls were **cut to budget** in the
  period (see below) when that number is non-zero.

### Daily volume and top tables [#daily-volume-and-top-tables]

A 30-day bar chart of calls vs. errors per day, plus two ranked tables:
**top tools** (which tool names are called most, with their error
counts) and **top users** (who's generating the most call volume).

A third table, **heaviest tools by response size**, exists specifically
to answer "which tool should be trimmed next": every MCP tool result has
a size budget (large results are explicitly cut, never silently
truncated), and this table surfaces which tools are hitting that ceiling
most often, sorted by average response size with a badge on any tool
that's actually being cut.

### Recent calls [#recent-calls]

A live, cursor-paginated tail of individual calls: timestamp, user, tool
name, which client made the call, duration, response size (with a
scissors badge when that call's response was cut to budget), and the
result - a green checkmark, or the HTTP status code plus the error
message for a failure.

{/* screenshot: Admin - MCP usage page, recent calls table with a truncated-response badge on one row */}

## Per-call logging [#per-call-logging]

Every MCP tool call your workspace processes is logged with enough
detail to answer "what did this AI client actually do, and when" without
needing server log access: the calling user, the tool name, the client
identifier, duration, response size, success/failure, and (on failure)
the status code and error message. This is what powers both the usage
dashboard above and any manual audit of a specific incident - if a user
reports something unexpected happened through their AI assistant, this
log is where you go to see exactly which tool was called and what came
back.

## The kill switch [#the-kill-switch]

**MCP server** on **Admin -> System settings** is a single toggle that
turns MCP access off for the **entire workspace** at once, regardless of
which individual users hold the per-user MCP permission. Use it for
compliance freezes, incident response, or staged rollouts where you want
to disable the whole surface without touching individual user
permissions.

{/* screenshot: Admin - System settings, MCP server card with the toggle */}

The toggle defaults to **on** - a fresh workspace with no explicit
setting behaves as if MCP is enabled. Turning it off:

* Blocks new MCP sessions and tool calls workspace-wide.
* Refuses OAuth token renewal for existing connections, so a client that
  was mid-session eventually loses access as its token needs refreshing
  rather than being forcibly disconnected mid-call.
* Is audit-logged with the actor and the before/after state, so a flip
  is always traceable to who did it and when.

Individual per-user access still layers on top: even with the
workspace switch on, a specific user still needs the `mcp:use`
permission (via their role) to actually use MCP - the workspace switch
and the per-user permission are two independent gates, both must be
open.

## Troubleshooting [#troubleshooting]

* **A user reports MCP tools aren't working, but the dashboard shows
  calls succeeding for other users** - check whether that specific
  user's role grants `mcp:use`; the workspace kill switch is all-or-
  nothing, but per-user access still depends on their own permissions.
* **Everyone lost MCP access at once** - check **Admin -> System
  settings -> MCP server**; someone likely flipped the workspace kill
  switch, and the audit log names who and when.
* **The usage dashboard shows a spike in errors from one tool** - open
  **Recent calls**, filter by eye on that tool's rows, and read the
  status code and error message directly; that's usually enough to tell
  whether it's a permission issue (403s from one user) or something
  systemic (5xx across many users).
* **A tool keeps showing the "cut" badge** - its response is larger than
  the tool's size budget and is being explicitly trimmed rather than
  sent in full; this is intentional cost control, not a bug, but it's
  worth flagging if you rely on that tool's full output regularly.
* **An AI client that was previously connected quietly stopped
  responding after I disabled MCP** - expected: the kill switch refuses
  token renewal rather than forcing an immediate disconnect, so an
  active session degrades once its token needs refreshing rather than
  breaking mid-call.

## See also [#see-also]

* [MCP server setup](/agents-ai/mcp) - connecting a specific AI
  client (Claude Desktop, Cursor, Copilot, Codex), transports, and the
  full tool/resource/prompt surface.


# OAuth clients (/admin/platform/oauth-clients)



**Admin -> OAuth clients** lists every application that has registered
to sign users into orboto through OAuth, instead of a long-lived API
key - typically an AI client like Claude Desktop, Cursor, or VS Code
Copilot connecting to orboto's [MCP server](/agents-ai/mcp).

## What an OAuth client is [#what-an-oauth-client-is]

When an app wants to act on a user's behalf without ever seeing that
user's password, it uses **OAuth**: the user is sent to orboto's own
login page, logs in there (or is already logged in), sees a consent
screen naming the app and what it's asking for, and - if they approve -
orboto hands the app a short-lived token scoped to that one user. The
app itself, registered ahead of time as an **OAuth client**, is
identified by a `client_id`; orboto tracks every client that has ever
completed this flow against your workspace, plus every user who has
individually authorized it.

This matters for security because it means an AI client never needs a
copy-pasted, long-lived API key sitting in a config file - each user
authorizes their own access, that access can be revoked per user
without affecting anyone else connected through the same client, and
the whole exchange is visible on this page.

## How a client gets here [#how-a-client-gets-here]

Two ways a client ends up in the list:

* **Auto-registered (dynamic)** - most MCP-aware AI clients register
  themselves automatically the first time someone points them at your
  orboto instance's `/mcp` URL and completes the OAuth flow. You don't
  do anything to make this happen; it shows up on this page once the
  first user finishes authorizing it.
* **Operator (pre-seeded)** - a client an administrator configures ahead
  of time rather than letting it self-register. These can only be
  removed via configuration, not the delete button in this list.

## The authorize flow an end user sees [#the-authorize-flow-an-end-user-sees]

This is what happens on the user's side when they connect an AI client
to orboto - useful to know so you can tell a colleague what to expect:

1. In the AI client (Claude Desktop, Cursor, VS Code, ...), they add
   orboto's MCP URL as a new connector/server.
2. The client opens a browser to orboto's login page (or reuses an
   existing session if they're already signed in).
3. orboto shows a **consent screen** naming the requesting app and what
   it's asking for, plus - where offered - a choice of **which identity
   to connect as**: themselves, or an agent account they own.
4. They click **Authorize**. The browser redirects back to the AI
   client, which now has a working, scoped session.

{/* screenshot: the orboto OAuth consent screen with the client name and identity picker */}

No API key is copy-pasted anywhere in this flow, and the resulting
access token rotates automatically without the user doing anything
further. The full connect walkthrough per client (Claude Desktop,
Cursor, Copilot, Codex) lives in
[MCP server setup](/agents-ai/mcp) - this page is the admin side:
what shows up here once people have connected, and how to manage it.

## What you see per client [#what-you-see-per-client]

Each row shows the client's name and `client_id`, whether it's
**auto-registered** or **operator**, when it was first registered, when
it was last used, and how many users currently have an active
authorization against it.

Click the **eye icon** on a row to open its authorized-users list - every
user with a live grant on that client, when it was issued, and when it
expires. From there you can **Revoke** any individual user's
authorization: their next call through that client fails, and they have
to go through the consent screen again to reconnect. Revoked
authorizations move to a separate section on the same view, tagged with
why they were revoked (an admin revoke, the user disconnecting it
themselves, the user opting out of MCP entirely, or a security-related
token-reuse detection) so you can answer "why did this stop working"
without digging through logs.

{/* screenshot: the client authorizations modal, active users table plus the revoked section with reason badges */}

## Scopes [#scopes]

An OAuth grant is scoped, not all-or-nothing: the client only ever
receives an `mcp:use`-equivalent grant tied to the authorizing user's
own permissions - it can't act with any access the user themselves
doesn't already have. Delegating to an **agent account** (offered on the
consent screen) attributes the connection's actions, timers, and time
entries to that agent instead of the person authorizing it, and the
connection runs with the agent's own permission set - the person's own
personal timer and timesheet stay untouched. Either way, permission
enforcement happens the same way it does for any logged-in user or API
key: nothing here bypasses orboto's normal access control.

## Deleting a client [#deleting-a-client]

Deleting an auto-registered (dynamic) client immediately invalidates
**every** user's authorization against it - not just one. A confirmation
dialog spells this out before it happens. Operator (pre-seeded) clients
can't be deleted from this page at all; that's a deliberate guard
against accidentally removing a client your deployment configuration
depends on.

## Housekeeping: prune unused clients [#housekeeping-prune-unused-clients]

Over time, dynamic clients that were only ever tried once (or where the
integration was abandoned) accumulate. **Prune unused dynamic clients**
removes every dynamic client that currently has **zero active
authorizations** *and* hasn't been used in **30 or more days** - a
one-click cleanup that never touches a client anyone is still actively
using, and never touches operator-configured clients at all.

## Coupling session revoke to MCP grant revoke [#coupling-session-revoke-to-mcp-grant-revoke]

By default, force-logging a user out (revoking their login session as an
admin) does **not** also revoke their MCP OAuth grants - a long-running
agent process shouldn't be interrupted just because someone force-logged
the person out of the web UI elsewhere. The toggle **Revoke MCP grants
on session revoke** changes that: when it's on, an admin force-logout
also revokes the user's MCP grants and clears their persisted MCP
sessions, so an AI client genuinely can't keep operating after the
person is signed out. It's off by default because aggressive revocation
interrupts long-running agents; the explicit per-user and per-client
**Revoke** actions above always work regardless of this setting, so you
can still revoke a specific grant surgically without flipping the
global toggle.

{/* screenshot: the Revoke MCP grants on session revoke toggle at the top of the OAuth clients page */}

## Troubleshooting [#troubleshooting]

* **A client I expect to see isn't listed** - it only appears after its
  first user completes the OAuth authorize flow; registering a client
  doesn't itself create a list entry until someone connects through it.
* **Delete is greyed out on a client** - it's an operator (pre-seeded)
  client; those are removed via configuration, not this list, precisely
  so a deployment's expected clients can't vanish from an accidental
  click.
* **A user says their AI client suddenly can't reach orboto** - check
  their row under that client's authorized-users list; if it's moved to
  the revoked section, the badge names why (their own disconnect, an
  admin revoke, an MCP opt-out, or a security-triggered revoke from
  token-reuse detection).
* **Prune unused dynamic clients removed something I still wanted** -
  it only ever removes clients with zero active authorizations that
  haven't been used in 30+ days; if a client qualified, it genuinely
  had no active users and no recent activity. Reconnecting simply
  re-registers it.


# Primer facts (/admin/platform/primer-facts)



## The concept [#the-concept]

When an AI agent (or a human relying on AI-generated context) starts
work on a project, it needs to know things a codebase alone can't
always tell it: which package manager to use, that a particular
migration step is handwritten rather than generated, what the
deployment process actually looks like, or a hard-won gotcha that cost
someone a debugging session last month. Writing this down once, in a
structured way, is far more reliable than hoping an agent rediscovers it

* or worse, guesses wrong - every single time.

A **primer fact** is exactly that: one small, structured piece of
project (or workspace) knowledge - a key, a value, and a category -
that gets automatically included whenever an agent (or a generated
report) asks for a project's **primer**: its onboarding briefing.

## Categories [#categories]

Every fact belongs to one category, which determines where it renders
in the primer and in generated reports:

| Category       | What belongs here                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------- |
| Tech stack     | Languages, frameworks, major dependencies, versions                                                |
| Conventions    | Coding standards, naming rules, commit message format                                              |
| Deployment     | How and where the project ships, environment specifics                                             |
| Architecture   | High-level structure, module boundaries, key design decisions                                      |
| Integrations   | External services and APIs the project talks to                                                    |
| Gotchas        | Hard-won, non-obvious pitfalls worth flagging up front                                             |
| Commands       | Exact CLI commands to build, test, run, or deploy                                                  |
| Non-functional | Explicit non-functional requirements - performance, security, data-protection, operational targets |
| Glossary       | Project- or domain-specific terminology and definitions                                            |
| Other          | Anything that doesn't fit the above                                                                |

## Scope: workspace vs. project [#scope-workspace-vs-project]

A fact is either **project-scoped** (visible only in that project's
primer) or **workspace-scoped** (visible in *every* project's primer,
automatically). Workspace facts are for things genuinely true
everywhere - a company-wide coding convention, a shared deployment
platform - not project specifics. Because a workspace fact adds to
*every* project's primer regardless of relevance, the admin UI shows a
standing reminder to use this scope sparingly; a fact that only applies
to one project belongs there instead.

## Source: manual, imported, or agent-observed [#source-manual-imported-or-agent-observed]

A fact records where it came from:

* **Manual** - a person typed it in directly.
* **Imported** - it arrived via a data import from another system.
* **Agent-observed** - an AI agent, working on the project, noticed
  something worth recording and proposed it as a fact on its own.

Agent-observed facts start **unverified** - useful context, but not yet
confirmed accurate by a human - and that's exactly what the review queue
below exists for.

## Managing workspace facts (Admin -> Primer facts) [#managing-workspace-facts-admin---primer-facts]

The **Workspace facts** tab lists every workspace-scoped fact (visible
in *every* project's primer). Filter by category and by verified state.

* **Add workspace fact** - create one directly, choosing its category,
  key, and value.
* **Edit** (pencil icon) - change an existing fact's content.
* **Supersede** - replace a fact with a new version while keeping the
  old one's history rather than silently overwriting it; use this when
  the old value was genuinely correct at the time but has since changed
  (a version bump, a process change), so there's still a record of what
  used to be true.
* **Verify** (shield icon) - mark a fact as human-confirmed accurate.
* **Delete** - remove it outright, with a confirmation naming the fact's
  key.

{/* screenshot: Admin - Primer facts page, Workspace facts tab with the category/verified filters */}

## Reviewing agent-observed facts (Pending review) [#reviewing-agent-observed-facts-pending-review]

The **Pending review** tab is a cross-project queue of every
agent-observed fact that hasn't yet been verified by a human -
regardless of which project (or the workspace scope) it belongs to. A
badge on the tab shows the current queue count.

Filter by project (or workspace scope) and category, then work each
entry with one of three actions:

* **Verify** - confirm it's accurate as written; it flips to verified
  and stops appearing in this queue.
* **Edit** - correct the wording or value before verifying it, for a fact
  that's directionally right but needs a fix. Editing doesn't
  auto-verify it - a deliberate **Verify** click afterward is still
  required, so an edit alone can't silently mark something as
  human-confirmed.
* **Reject** - remove it, with a required reason captured in the audit
  log, for a fact that's simply wrong or not worth keeping. This is the
  one place in the primer-facts UI with an explicit "why" prompt,
  because a rejected agent observation is worth knowing the reason for
  later (was the agent wrong, or just capturing something too
  transient to keep?).

{/* screenshot: Admin - Primer facts page, Pending review tab with the Verify/Edit/Reject actions on one entry */}

## Where facts surface [#where-facts-surface]

* **The project primer** - the structured briefing an AI agent or the
  MCP/skill surfaces pull when it starts work on a project. Facts render
  grouped by category, in a fixed display order, with workspace facts
  merged in alongside that project's own.
* **Generated requirements-style reports** - the *non-functional* and
  *glossary* categories specifically exist to feed the matching chapters
  of orboto's generated requirements specification report, so those
  categories carry weight beyond just agent context.
* **Personal facts** - a related, separate concept: individual users can
  also record their *own* personal facts (visible only to them across
  the projects they work in), which is a different surface from the
  workspace/project facts this admin page manages.

## Why verification matters [#why-verification-matters]

An agent proposing "the deploy command is `X`" and being wrong costs
real time the next time an agent (or a person) trusts it. Verification
is the deliberate human checkpoint between "an agent noticed this" and
"this is now treated as reliable project knowledge" every future agent
session will be handed as fact. Leaving agent-observed facts unverified
indefinitely isn't dangerous by itself - unverified facts still surface
in the primer - but reviewing the queue regularly is what keeps
project knowledge trustworthy rather than merely plausible.

## Troubleshooting [#troubleshooting]

* **A fact I added to one project shows up in every project's primer**
  * it was created at workspace scope instead of project scope; edit it
    (or delete and re-add it under the specific project) to narrow it.
* **An agent keeps re-proposing the same fact after I rejected it** -
  rejection removes that specific fact record, but doesn't prevent an
  agent from observing the same thing again in a later session; if it
  keeps recurring and is actually correct, verifying it once (or adding
  it manually) stops the cycle since it will no longer look "new" to the
  agent.
* **The pending-review badge count doesn't match what I see after
  filtering** - the badge counts the full cross-project queue; your
  current project/category filter narrows what's displayed without
  changing the underlying count until you act on entries.
* **A category I need isn't in the list** - the category set above is
  fixed; use **Other** for anything that doesn't fit, or note the gap
  for your workspace's own conventions rather than trying to force a fit
  into an unrelated category.


# Bring your own key (BYOK) (/admin/security/byok)



**Bring your own key (BYOK)** is an Enterprise feature
(`Admin -> Encryption keys (BYOK)`) that lets you control the
encryption key protecting orboto's stored secrets, instead of relying
solely on the key orboto generates for you. This page starts from the
underlying concept - **envelope encryption** - then walks through
configuring, testing, rotating, and (if it's ever needed) recovering
from a revoked key.

It's on a single Docker image: BYOK works the same way on every
orboto edition. Without an active Enterprise license it still runs, but
the standard soft-warn banner appears on the License page once you
activate a customer-managed key.

## The concept: envelope encryption [#the-concept-envelope-encryption]

Every secret orboto stores at rest - a Git access token, an SSO client
secret, an MFA TOTP seed, and more (full list below) - needs to be
encrypted before it touches the database. The naive approach is one key
that encrypts everything directly; the problem with that is rotating the
key means re-encrypting every single secret in one atomic operation, and
if the key ever leaks, every secret it protected is exposed at once.

**Envelope encryption** solves this with two layers of key instead of
one:

1. Each individual secret gets its own randomly-generated &#x2A;*data key
   (DEK)**, used once to encrypt just that secret.
2. The DEK itself - a small, 32-byte value - is then encrypted
   ("wrapped") by a separate &#x2A;*key-encryption key (KEK)**, and it's the
   *wrapped DEK* that's stored alongside the encrypted secret, never the
   DEK in plaintext.

The KEK is the only key you ever need to protect, rotate, or revoke -
and because it never encrypts the secret data directly (only the small
DEKs), rotating it means re-wrapping thousands of small DEKs, not
re-encrypting the underlying secrets themselves. Revoking the KEK at
your key-management system makes every secret it wrapped **unreadable**,
instantly and without touching the database at all - orboto's server
never persists an unwrapped KEK, so there's nothing on the orboto side
that could still decrypt it.

**BYOK** is what it sounds like: you choose and control that KEK,
instead of using the server-derived one orboto uses by default.

## What gets wrapped [#what-gets-wrapped]

Every at-rest secret in orboto routes through the same envelope-encryption
seam, so switching KEK provider protects all of them at once:

* Git connection access tokens and OAuth refresh tokens, GitHub App
  private key and webhook secret
* SSO provider config (OIDC client secret, SAML certificate and SP
  private key)
* MFA TOTP secrets
* SIEM audit-forwarder HMAC secret
* Federation outgoing tokens
* Inbound IMAP passwords
* Backup destination S3 secret keys
* Assorted `system_config` secret slots - every `*_encrypted` key, the
  SCIM outbound webhook secret, and the mail-service API key

Reads stay format-aware: a value wrapped under the envelope scheme is
opened with the provider named inside it, while an older (pre-BYOK)
value is still read correctly with the legacy key and silently
re-wrapped into an envelope the next time it's written. **There's no
migration step to adopt BYOK** - existing data keeps working from the
moment you activate a provider, and each secret upgrades to the new
scheme lazily as it's next touched.

## Providers [#providers]

| Provider                      | Where the KEK lives                                                                           | Config you provide     |
| ----------------------------- | --------------------------------------------------------------------------------------------- | ---------------------- |
| Built-in server key (default) | Derived from orboto's own server secret                                                       | None                   |
| AWS KMS                       | Amazon Key Management Service                                                                 | KMS key ID, AWS region |
| Customer key file             | A file on the API host's filesystem (self-hosted / air-gapped)                                | Path to the key file   |
| External KMS (HTTP)           | Any HTTP-reachable key service - HashiCorp Vault, or a thin adapter in front of GCP/Azure KMS | Base URL, bearer token |

The external-KMS option speaks a minimal HTTP contract: your endpoint
must accept `POST {baseUrl}/wrap` with `{"dek": "<base64>"}` and return
`{"result": "<base64>"}`, and the mirror `POST {baseUrl}/unwrap` with
`{"wrapped": "<base64>"}` returning `{"result": "<base64>"}`, optionally
behind an `Authorization: Bearer <token>` header. This is a thin,
implementable-in-an-afternoon contract in front of whatever KMS you
actually run.

One important distinction: the provider **configuration values**
themselves (the AWS key ID, the external KMS URL and token, the key-file
path) are your infrastructure credentials, not BYOK-sealed secrets -
they're stored as-is (masked on read) rather than run through the
envelope scheme, because the external-KMS token is what bootstraps the
very provider that would otherwise need to unseal it. Protect these
values the way you protect any other deployment credential, such as
`JWT_SECRET`.

## Configure [#configure]

1. Go to &#x2A;*Admin -> Encryption keys (BYOK)**.
2. Pick a **provider** and fill in its configuration fields.
3. Click **Test connection** first. This performs a real wrap/unwrap
   round-trip against the provider you just configured and reports the
   exact failure if something's wrong (a bad key ID, an unreachable
   endpoint, a missing key file) - so a misconfiguration surfaces here,
   not on the next production read that happens to need it.
4. Click **Save & activate**. The provider is registered and switched
   live for the running process immediately - no restart required. Every
   new secret from this point on is sealed under it; secrets already
   sealed under a different provider keep reading correctly through
   their own provider until they're next rotated or rewritten.

{/* screenshot: Admin - Encryption keys (BYOK) page, provider picker with the Test connection and Save & activate buttons */}

On the next server boot, the configured provider re-activates
automatically - you don't need to repeat this setup after a restart or
deploy.

## Rotate [#rotate]

**Rotation** re-wraps every stored secret's data key onto whichever KEK
is currently active - the standard operational hygiene step after a
scheduled key change, or after any event that makes you want a fresh
key in play.

1. Activate the new KEK first (the Configure steps above).
2. On the same page, under **Key rotation**, click **Rotate now**, then
   confirm.
3. A summary reports counts per outcome: **re-wrapped**,
   **already-current** (already on the active provider, nothing to do),
   **legacy-skipped** (an old plaintext or pre-BYOK value with no DEK to
   re-wrap yet - it upgrades on its own next write instead), and
   **failed**.

{/* screenshot: Admin - Encryption keys (BYOK) page, rotation summary with per-site counts */}

Rotation is **idempotent and resumable** - re-running it after a partial
pass only finishes whatever's left, since anything already on the
active provider is skipped. It's also safe to run *during* live traffic:
each secret is read through whichever provider it's actually wrapped
under at read time, so a half-rotated table has old-provider and
new-provider blobs side by side, and both decrypt correctly, the whole
time. A row that fails to rotate (for example its old KEK was revoked
mid-rotation, so it can no longer be unwrapped to re-wrap) is logged,
counted as failed, and left untouched rather than corrupted - fix the
underlying KMS issue and re-run; only the still-failing rows are
touched on the next pass.

## Revoke [#revoke]

There is deliberately **no "revoke" button in orboto**. True revocation
happens on the KMS side: disable or delete the KEK at AWS KMS, in Vault,
or at your external KMS. The instant you do that, every secret wrapped
by that key becomes **fail-closed unreadable** - the unwrap operation
throws, and orboto never falls back to reading the value as plaintext.

The practical effect of a revocation:

* Any feature that needs a revoked secret to function - Git sync, SSO,
  MFA, the SIEM forwarder, inbound IMAP, federation, backups - stops
  working outright (no valid token/signature/connection) rather than
  silently exposing anything.
* Switching the provider back to the built-in default in the admin UI
  only changes which key **new** secrets get sealed under going forward.
  It **cannot** un-revoke or re-read secrets that were already sealed
  under the now-revoked KEK - that data is genuinely gone unless the KEK
  is restored at the KMS. To recover, either restore the KEK at your KMS
  (if your KMS supports un-revoking), or re-enter the affected
  credentials by hand (reconnect the Git integration, reconfigure SSO,
  and so on).

## Fail-closed contract [#fail-closed-contract]

If the active provider - or any provider a stored value names - can't
wrap or unwrap (the KMS is unreachable, the key was revoked, the key
file is missing), the operation **throws**. There is never a silent
plaintext fallback, at any point in the read or write path. This is
exactly why **Test connection** exists as a separate, non-destructive
step before **Save & activate**: it lets you catch a misconfigured
provider with a deliberate round-trip check, rather than discovering it
the first time a real production read needs the key and fails.

## Troubleshooting [#troubleshooting]

* **Test connection fails** - read the reported error; it names the
  specific cause (unreachable endpoint, bad key ID, missing file) rather
  than a generic failure, so start there before re-checking the whole
  configuration.
* **A feature stopped working right after a KMS-side change** - check
  whether the KEK it depends on was revoked or disabled at the KMS; this
  is the expected fail-closed behavior, not a bug, and the fix is either
  to restore the key at the KMS or re-enter the affected credential.
* **Rotation reports failures** - each failure names the site and
  record id; the most common cause is a KEK that stopped being valid
  partway through the rotation (revoked, expired, or a permissions
  change on the KMS side). Fix the underlying KMS access and re-run
  rotation - only the still-failing rows are retried.
* **I switched the provider back to the built-in key, but old secrets
  still won't read** - this is expected if the KEK they were sealed
  under has been revoked; switching the active provider only affects
  new seals, it can't retroactively decrypt values already sealed under
  a now-unavailable key.


# Data retention and legal holds (/admin/security/data-retention)



**Data retention** and **legal holds** are two sides of the same
control: retention automatically gets rid of data past a configured
age, and a legal hold is the explicit override that says "not this
one, not yet" regardless of age. Both live on **Admin -> Compliance**,
alongside data-subject request (DSAR) handling.

This page explains the two concepts from first principles and walks
through the operator actions (preview, run, place, release). For the
full field-by-field reference of every setting on the Compliance page -
including the DSAR workflow these two features sit next to - see
[Data protection (GDPR)](/admin/operations/data-protection).

## What retention is for [#what-retention-is-for]

Keeping data forever is a liability, not a feature: old closed tickets,
years of audit-log rows, and stale notifications accumulate storage cost
and expand what a data breach could expose, without adding value to
anyone still using the workspace. A **retention policy** says, per data
category, "once this is older than N days, get rid of it automatically"

* so cleanup happens on a schedule instead of depending on someone
  remembering to do it manually.

orboto's retention policy covers three categories independently, each
with its own age threshold in days (`0` means keep forever for that
category, i.e. retention is off for it):

* **Closed tickets** - past their configured age, either **deleted** or
  **anonymized** (your choice per policy - anonymize keeps the ticket
  for statistics/reporting but strips the identifying content).
* **Audit log** - old audit-trail rows.
* **Notifications** - old in-app notification rows.

A background job applies the policy once a day. You don't have to wait
for it, though - see **Preview and run manually**, below.

## What a legal hold is for [#what-a-legal-hold-is-for]

A **legal hold** (sometimes called a litigation hold) is a preservation
order: "this specific project / user / ticket must not be deleted or
anonymized, for any reason, until I say otherwise" - typically because
it's evidence in an active dispute, investigation, or audit. A hold
overrides *everything* that would otherwise remove or anonymize data in
its scope: the retention job above, and any manual delete/anonymize
action elsewhere in the product (including DSAR erasure requests).

Holds are scoped to exactly one **project**, **user**, or **ticket** at a
time (by its UUID) with a required **reason** - if you need to preserve
several things, place several holds.

## Preview and run manually [#preview-and-run-manually]

Waiting for tomorrow's scheduled run isn't always convenient - right
after tightening a retention policy, you'll usually want to know its
effect immediately. Two buttons on the Retention card do this:

1. **Preview (dry-run)** - runs the exact same purge logic as the
   scheduled job, but **deletes nothing**. It reports how many tickets,
   audit-log rows, and notifications *would* be purged under the current
   policy, plus how many tickets were skipped because they're under an
   active legal hold.
2. **Run purge now** - the real, destructive run. Clicking it doesn't
   purge immediately: a confirmation step appears with an explicit
   **Confirm - delete permanently** button, so a single misclick can't
   trigger an irreversible bulk delete. Once confirmed, it reports the
   same counts as the preview, except this time the data is actually
   gone (or anonymized, per the ticket action setting).

{/* screenshot: Admin - Compliance page, Data retention card with the Preview / Run purge now buttons and a result summary */}

Always **Preview** before you **Run**, especially the first time you
configure a new threshold - it's the only way to see the real numbers
before committing to a delete.

## Placing and releasing a hold [#placing-and-releasing-a-hold]

1. On the **Legal hold** card, pick the **scope type** (Project / User /
   Ticket).
2. Paste the specific **scope UUID** you want to preserve.
3. Enter a **reason** - required, and shown in the hold list so anyone
   reviewing it later (including you, months from now) understands why
   it exists.
4. Click **Place hold**.

The hold appears in the list below with its scope, a truncated id, and
the reason. Click **Release** on any entry once the hold is no longer
needed - release takes effect immediately with no extra confirmation,
since releasing a hold doesn't delete anything by itself; it simply
re-exposes that scope to the normal retention and manual-deletion rules
going forward.

Every place and release is written to the audit log with the actor and
the reason, so the *history* of what was held and when is preserved even
after a hold is released.

## Troubleshooting [#troubleshooting]

* **Something under a legal hold won't delete or anonymize, and there's
  no error explaining why** - this is by design: a hold blocks the
  action silently from the acting user's point of view unless they know
  to check here. Look up the exact scope UUID on the Legal hold card.
* **Preview shows 0 for a category I expect to have old data** -
  confirm that category's threshold isn't `0` (which means "keep
  forever," not a bug), and check whether the data you expected is
  actually under a hold (Preview reports held-tickets-skipped
  separately from the purge counts).
* **Run purge now did less than the preview reported** - a hold placed
  between the preview and the run would explain the gap; otherwise the
  counts should match exactly, since both use the same logic.
* **You need to preserve a whole project, not just one ticket** - place
  the hold with scope type **Project**; every ticket in that project is
  then covered, you don't need one hold per ticket.

## See also [#see-also]

* [Data protection (GDPR)](/admin/operations/data-protection) - the
  full Compliance page reference, including data-subject request (DSAR)
  handling that sits alongside retention and legal holds.


# Session, password and network policies (/admin/security/security-policies)



**Admin -> Security** collects the access-hardening settings that apply
across the whole workspace: how long a signed-in session is allowed to
last, what a password must look like, and which networks are allowed to
reach the workspace at all. Two-factor authentication also lives on this
page, but it's big enough to get [its own guide](/admin/identity/two-factor)

* this page covers the other three cards.

Each card is independent and self-gating: you only see the cards your
own permissions let you read, and the inputs are disabled (not hidden)
if you can read but not write. Reading needs the matching `:read`
permission (`admin:session-policy:read`, `admin:password-policy:read`
via `admin:system:read`); writing needs the `:write` counterpart.

{/* screenshot: Admin - Security page with all three cards visible */}

## Session security policy [#session-security-policy]

A **session** is the signed-in state a browser holds after you log in -
normally it just keeps working for a fixed period (7 days by default) as
long as you keep using it. This card lets you tighten that default with
four independent knobs. All four start **off** (0, or unset) - an
unconfigured workspace behaves exactly as it always has.

* **Idle timeout (minutes, 0 = off)** - sign a session out automatically
  after this many minutes of no activity. Every request pushes the
  timeout window forward, so an active user never sees it; someone who
  walks away from an unlocked laptop does.
* **Absolute lifetime (minutes, 0 = off)** - a hard cap on how long a
  session can live, counted from the moment it was created, regardless
  of activity. Even a continuously-used session is forced to re-log-in
  once this elapses. Use this where policy requires periodic
  re-authentication no matter what.
* **Max concurrent sessions (0 = off)** - the most sessions one user can
  have live at the same time (think: logged in on a laptop, a phone, and
  a second browser profile). Sign in past the limit and the *oldest*
  session is evicted automatically - not the newest, so the person who
  just signed in stays signed in and the one they forgot about elsewhere
  gets kicked.
* **Revoke a user's sessions when their role changes** - on by default.
  When someone's project role or global role changes, every one of their
  live sessions is immediately terminated so the new (tighter or looser)
  permission set only takes effect after they log back in. Without this,
  a user whose access was just revoked could keep acting on their old
  permission set for as long as their existing session token remains
  valid.

These knobs only ever govern **human browser sessions**. API keys and AI
client (MCP / OAuth) tokens authenticate differently and are never
affected by any setting on this card - an automation you've set up
doesn't get silently logged out because you set a 30-minute idle
timeout for people.

## Password policy [#password-policy]

Rules enforced every time a **local** (password-based) account sets,
changes, or resets its password. Every rule starts at its most
permissive value, so turning this card on is opt-in, not a surprise
change to existing accounts on upgrade.

* **Minimum length** - shortest password accepted (default 8).
* **Require uppercase / lowercase / a number / a symbol** - four
  independent character-class checkboxes; turn on only the ones you
  need. A password failing any checked rule is rejected with a specific
  reason, not a generic "invalid password" message.
* **Expiry (days, 0 = off)** - force a password change after this many
  days. `0` means passwords never expire on their own.
* **Block last N reused (0 = off)** - reject a new password that matches
  any of the account's last N passwords. `0` means no reuse check at
  all; orboto only stores the number of historical hashes your current
  setting actually needs to check, so raising this later re-establishes
  history going forward rather than retroactively.
* **Reject passwords found in known breaches (HaveIBeenPwned,
  privacy-preserving)** - checks the candidate password against the
  [HaveIBeenPwned](https://haveibeenpwned.com/) breach corpus using
  k-anonymity: only the first 5 characters of the password's SHA-1 hash
  ever leave the server, so the real password (and even its full hash)
  is never transmitted. If the breach-check service is unreachable, the
  check fails open (the password is allowed) rather than blocking
  sign-ups during a third-party outage.
* **Disable local passwords when SSO is mandatory** - once your
  workspace enforces [SSO](/admin/identity/sso) for a domain, this
  additionally blocks setting or keeping a local password for accounts
  on that domain, closing the "local password as a side door around SSO"
  gap.

## IP allowlist [#ip-allowlist]

Restrict which networks can reach the workspace at all, by CIDR range
(e.g. `10.0.0.0/8` for a whole private range, or `203.0.113.4/32` for a
single address). Paste one CIDR per line into the text box - both IPv4
and IPv6 ranges are accepted.

Two scope modes:

* **All authenticated traffic** - every request from a signed-in user
  (or API key) must originate from an allowed network.
* **Admin routes + writes only** - only `/admin/*` routes and mutating
  requests (POST/PUT/PATCH/DELETE) are restricted; plain reads from
  outside the allowlist still work. Use this to protect *changing*
  workspace state and admin surfaces without locking regular users out
  of read access from anywhere.

An **empty list means unrestricted** - this feature is off by default,
and stays off until you add at least one CIDR.

### The break-glass guarantee [#the-break-glass-guarantee]

Super-admin accounts **always bypass the allowlist**, on every scope.
This exists specifically so a misconfigured or overly-narrow CIDR can
never lock every admin out of their own workspace - fix the range from
outside the allowlist as a super-admin, then re-save it. Non-super-admin
accounts get no such exception: get the range wrong for a project admin
and they really are locked out until a super-admin corrects it.

## Edition note [#edition-note]

All three cards work on every orboto edition. On Community they raise
the standard soft-warn banner on the License page once a rule is
actually enforcing something (a non-default password rule, a non-zero
session TTL knob, or a non-empty IP allowlist) - nothing is blocked.

## Troubleshooting [#troubleshooting]

* **I can't reach `/admin` anymore after saving an IP allowlist** - if
  you're a super-admin, the break-glass bypass means this shouldn't
  happen; if you're not, ask a super-admin to correct or clear the
  allowlist from a network the range does cover (or from their
  break-glass access).
* **A password that looks fine is rejected** - check each rule
  individually; the error names the first rule the password fails
  (length, a missing character class, reuse, or a breach-corpus hit),
  not just "invalid".
* **The breach check seems to be doing nothing** - it fails open by
  design when the HaveIBeenPwned API is unreachable, so a network outage
  on your server never blocks legitimate password changes; it isn't a
  bypass a user can trigger deliberately.
* **A user got signed out unexpectedly workspace-wide** - check whether
  their role changed recently (the revoke-on-role-change toggle is on by
  default) before assuming a bug; also check the idle timeout and
  absolute lifetime settings if it happened mid-session.
* **Signing in on a new device unexpectedly signs out an old one** -
  that's the max-concurrent-sessions cap evicting the oldest session,
  working as intended, not an error.


# Account and security (/user-guide/everyday/account-and-security)



Your **profile** is where you manage how you appear, how you sign in, and how securely. Open it by selecting your avatar and name at the bottom of the sidebar, or go to the profile page directly.

{/* screenshot: the profile page with avatar, password, two-factor and sessions sections */}

## Your identity [#your-identity]

* **Avatar** - upload a picture, or let orboto generate a coloured initials avatar. You can pick the **avatar colour** or leave it automatic.
* **Name and email** - shown to teammates on tickets, comments, and mentions.
* **Theme** - Light, Dark, or System (also on the sidebar switch).
* **Language** - the interface language.
* **Availability visible to teammates** - lets colleagues see a green/amber/red capacity badge for you in assignee pickers. Your actual calendar details are never shared, only that busy/available signal - turn it off to hide even that.

## Password [#password]

In the **password** section, change your password by entering your current password and a new one. If your workspace uses single sign-on, you may sign in without a password at all.

## Two-factor authentication [#two-factor-authentication]

**Two-factor authentication** (2FA) adds a second step at sign-in so a stolen password is not enough. orboto supports two kinds, and you can use both.

{/* screenshot: the two-factor section showing the authenticator setup and passkey list */}

### Authenticator app (one-time codes) [#authenticator-app-one-time-codes]

1. Select **Enable** in the two-factor section.
2. Scan the shown **QR code** with an authenticator app on your phone (or type the key manually).
3. Enter the six-digit code the app shows to confirm.
4. **Save your recovery codes.** These one-time backup codes let you get in if you lose your phone - store them somewhere safe. Without them, losing your device can lock you out.

To turn it off later, use **Disable** and confirm.

### Passkeys [#passkeys]

A **passkey** signs you in with your device's fingerprint, face, or PIN - no code to type, and nothing to phish.

1. Select **Add passkey**.
2. Give it a label (for example "work laptop") so you can recognise it later.
3. Follow your device's prompt to create the passkey.

Your registered passkeys are listed with when they were added and last used; **remove** any you no longer trust.

### The extra-confirmation prompt (step-up) [#the-extra-confirmation-prompt-step-up]

Some sensitive actions ask you to re-confirm your identity even though you are already signed in - this is called **step-up**. When it happens, a small dialog asks for your authenticator code (or passkey). Enter it and the action continues. This protects high-risk operations from being done by someone who wandered up to your unlocked screen.

{/* screenshot: the step-up re-confirmation dialog asking for a code */}

## Active sessions [#active-sessions]

The **sessions** section lists every device currently signed in to your account, with its last activity. Your current session is marked. If you see something you do not recognise, **revoke** that session, or **revoke all others** to sign out everywhere except here.

{/* screenshot: the active-sessions list with a revoke button per device */}

## Calendar feed and connected calendars [#calendar-feed-and-connected-calendars]

* **Calendar feed** - a personal, read-only iCal subscription URL you paste into Google Calendar, Apple Calendar, or Outlook. Choose which items it carries: absences, ticket due dates, milestones, and your timesheet-submission deadline. **Regenerate** the URL if it leaks, or **disable** the feed entirely.
* **Connected calendars** - connect Google Calendar, Microsoft 365, or a CalDAV server (which uses a server URL, username, and app password instead of the OAuth flow the other two use) so orboto and your calendar sync both ways: push your absences and planned work blocks out, and pull your busy times back in to feed the availability signal above. Each connection can be **resynced** on demand or **disconnected**.

{/* screenshot: the profile page's connected-calendars list with provider icons and a resync/disconnect action per account */}

## Email preferences [#email-preferences]

* **Daily digest email** - a once-a-day summary instead of many individual emails.

## Personal API keys [#personal-api-keys]

If you build scripts or connect other tools, the **API keys** section lets you create personal keys that act on your behalf through orboto's API:

1. Select **New key**, give it a name, and optionally set an **expiry date**.
2. Mark it as an **agent key** if a script or AI agent will use it - work done through an agent-flagged key is recorded as agent work rather than attributed as your own manual activity.
3. Create it - the secret is shown **once**. Copy it immediately; it is never shown again.
4. Later, **rotate** a key to issue a new secret while invalidating the old one (without recreating the key's name/settings), edit its expiry inline, or **delete** it when you no longer need it.

Treat a key like a password. For connecting AI clients specifically, see [Integrations](/integrations).

## Backup approver [#backup-approver]

If your workspace uses backups, you may be able to nominate a **backup approver** - a trusted colleague who can approve a sensitive restore on your behalf. Set this in your profile where offered.

## Troubleshooting [#troubleshooting]

* **I lost my phone and can't get in.** Use a saved **recovery code** from when you enrolled 2FA. If you have none, ask a workspace administrator to reset your two-factor setup.
* **A step-up prompt keeps interrupting me.** It only appears on genuinely sensitive actions (for example, changing security settings or approving a destructive AI action) - it is not something you can turn off, by design.
* **My API key stopped working.** Check its expiry date, or whether it was rotated (rotating issues a new secret and invalidates the old one immediately).
* **My calendar feed shows nothing.** Confirm the feed is enabled and at least one scope is turned on; some calendar apps cache a subscribed feed for several hours before refreshing.
* **A connected calendar shows a sync error.** Use **Resync** first; for CalDAV, a repeated failure usually means the server URL, username, or app password needs re-entering.


# Your dashboard (/user-guide/everyday/dashboard)



The **Dashboard** is the first screen you see after signing in. It is your personal home page - a grid of **widgets**, each showing one slice of what matters to you right now. You can choose which widgets appear and rearrange them; your layout is saved to your account and follows you to any device.

{/* screenshot: the dashboard with a mix of widgets - my tickets, stat cards, recent activity */}

## What the widgets show [#what-the-widgets-show]

Depending on what your administrator has enabled and what you add, widgets can include:

* **Stat cards** - four headline numbers: active projects, open alerts, remaining vacation days this year, and whether you have a running timer. Each one links to the matching page.
* **My tickets** - tickets assigned to you, sorted with blockers and high priority first, each showing status, priority, and due date.
* **Blocked tickets** - the same view narrowed to tickets that aren't moving.
* **Upcoming deadlines** - tickets with a due date coming up, labelled by working days remaining (for example "2 working days" or "3d overdue"), not calendar days.
* **Project progress** - a chosen project's completion, configurable per widget.
* **Recent activity** - the latest changes across your projects.
* **Recent projects** - the projects you opened most recently, with a "view all" shortcut.
* **Interesting tickets** - tickets the system thinks deserve your attention, based on similarity to your recent work.
* **Active alerts** - warnings currently firing (see [Planning and alerts](/user-guide/planning/planning-and-alerts)).
* **Time today** - how much time you have logged today against your goal.
* **Absence summary** and **Team availability** - who is off and who is free.
* **Custom saved search** - the live results of a search you saved, with a dropdown right on the widget to switch which saved search it shows.

Some widgets (federation status, primer health, and an agent-drift widget) only appear for administrators or in workspaces that use those features.

## Customising your dashboard [#customising-your-dashboard]

{/* screenshot: the dashboard customise dialog showing the widget list, size picker, and add-widget row */}

1. Select **Customise** in the dashboard header.
2. **Add a widget** from the catalogue of available types (each type can only be added once).
3. Drag a widget by its handle to reorder it - or **remove** it with the trash icon.
4. Set each widget's size to **Half** or **Full** width using its dropdown.
5. Select **Save**. Your layout persists to your account immediately.

If saving fails (for example, a connection hiccup), your changes stay in the dialog so you can retry - nothing is lost silently.

## Pinning a saved search as a widget [#pinning-a-saved-search-as-a-widget]

If you often re-run the same search, put its live results on your dashboard:

1. Create and save a search first (see [Search](/user-guide/knowledge/search)).
2. Add a **Custom saved search** widget to your dashboard.
3. Use the dropdown on the widget itself to point it at the saved search you want - it always shows current matches, no separate configuration screen needed.

## Guests see a simpler dashboard [#guests-see-a-simpler-dashboard]

If you are an external or guest user, your home screen is a focused list of just the projects and doc spaces that have been shared with you, rather than the full widget grid. See [Customers and guests](/user-guide/customers-and-guests).

## Troubleshooting [#troubleshooting]

* **A widget I want isn't in the "add" list.** Each widget type can only be added once - if it's already on your dashboard, add it isn't offered again; remove the existing one first if you want to re-add it with different settings.
* **A widget shows a blank or "unknown" card.** This can happen if a widget type your workspace no longer supports is still saved in your layout - remove it from Customise.
* **My saved-search widget shows no results.** Confirm the underlying saved search still returns matches on the [full search page](/user-guide/knowledge/search) - the widget mirrors it exactly.
* **I don't see the federation, primer-health, or agent widgets.** These are operator-facing and only shown to super-admins or users with the matching admin permission.


# Notifications (/user-guide/everyday/notifications)



orboto keeps you informed when something touches your work - you are mentioned, a ticket you own changes, an alert fires, a timesheet needs approval. Notifications reach you in the app, by email, and (optionally) in chat tools you already use.

## The notification bell [#the-notification-bell]

The **bell** in the top bar shows a badge when you have unread notifications. Select it for a quick list, and open the full **inbox** to see everything.

{/* screenshot: the notification bell dropdown with recent notifications */}

In the inbox you can:

* Read notifications and select one to jump to whatever it refers to.
* **Mark as read** individually or all at once.
* Filter to focus on what is unread.

{/* screenshot: the notifications inbox with a list of items and mark-all-read */}

## Choosing what you get notified about [#choosing-what-you-get-notified-about]

Open **Notification settings** from the gear icon in the top bar.

{/* screenshot: the notification settings page with per-event in-app, email, and channel toggles grouped by category */}

Events are grouped by area - **tickets** (assigned, unassigned, mentioned, commented, status changed, due date changed or auto-shifted, overdue), **versions** (rescheduled, released), **milestones** (dates changed), **projects** (member added, role changed, status changed), **docs** (mentioned, shared), **absences** (approved, rejected, submitted), **timesheets** (approved, rejected, submitted), and **alerts** (alert triggered, plus data-request deadline reminders where compliance features are on).

For each event you control delivery independently:

* **In-App** - shows in the bell and inbox.
* **Email** - sent to your account email (when email delivery is configured for the workspace).
* One toggle **per connected chat channel** - so a given event type can go to one channel, several, or none, without turning the channel off entirely.

Adjust each event to taste, or select **Reset to defaults** to start over. Sensible defaults are set for you when your account is created, so this is fine-tuning, not required setup.

## Chat channels (Discord, Slack, Teams, Telegram, and webhooks) [#chat-channels-discord-slack-teams-telegram-and-webhooks]

Add a channel to have notifications delivered outside the app:

1. In notification settings, select **Add channel**.
2. Choose the **channel type** - Discord, Slack, Microsoft Teams, Telegram, or a generic **webhook** - and give it a name.
3. Paste what that type needs: an incoming-webhook URL for Discord, Slack, or Teams (each shows short step-by-step help for finding it); a chat ID for Telegram. A generic webhook additionally takes an optional shared secret and up to five custom HTTP headers, for wiring your own receiver.
4. Save, then select **Verify** to send a test message - a channel stays **unverified** (and greyed out in the per-event chips) until it successfully receives one.

{/* screenshot: the add-channel dialog with the channel-type picker and webhook field */}

Once verified, the channel appears with a status badge and its own toggle per event type (above). **Remove** a channel you no longer need with the trash icon - this stops all delivery to it immediately.

## The daily digest [#the-daily-digest]

If you prefer one summary over a stream of individual emails, turn on the **daily digest email** in your [profile](/user-guide/everyday/account-and-security) - a single once-a-day roundup of what is happening on your work.

## Troubleshooting [#troubleshooting]

* **A channel never receives anything.** Check its status - an **unverified** channel is excluded from delivery even if its per-event toggle is on. Select **Verify** again.
* **I'm not getting emails.** Confirm email delivery is configured for your workspace (ask an administrator) and that the specific event's **Email** toggle is on - each event type is independent.
* **Too many notifications.** Turn off the noisier event types individually rather than disabling notifications wholesale, or switch to the [daily digest](#the-daily-digest) for a single daily summary instead of a stream.
* **I broke my preferences experimenting.** Select **Reset to defaults** at the top of the preferences section to start clean.


# Doc spaces (/user-guide/knowledge/doc-spaces)



A **space** is the container for documentation pages in orboto - a folder of related pages shown as a tree, covered from the reading and writing side in [Docs and wiki](/user-guide/knowledge/docs-and-wiki). This page is about the space itself: finding and creating spaces, their settings, and managing them as they grow.

## The space list [#the-space-list]

Open **Docs** in the sidebar to see every space you have access to.

{/* screenshot: the space list with global and project-scoped cards, the search box, and the scope/status filters */}

* Each card shows the space's name, description, and a **globe** icon (global, visible workspace-wide) or **folder** icon (project-scoped, linked to one project). A project-scoped card also names its owning project.
* **Search** narrows the list by name or description as you type.
* Two filters sit next to the search box: **scope** (global / project-scoped) and, for project-scoped spaces, the owning project's **status** (draft, active, archived, closed) - archived and closed projects' spaces are hidden by default so old work doesn't clutter the list, and you opt back in by ticking their status.
* A summary line ("Showing 6 of 9 spaces") appears whenever a filter is hiding something, so it is never a silent gap.
* Select the **pin** icon on a card (visible on hover, or always for a space you have already pinned) to pin it to your sidebar - a pinned space stays one click away under the sidebar's wiki section instead of requiring a trip back to this list.

## Creating a space [#creating-a-space]

1. Select **New space**. This is only available if you belong to at least one project (or are a super-admin) and are not an external/guest account - documentation authorship is an internal-team activity.
2. Give it a **name**.
3. Choose its **type**:
   * **Global** - visible workspace-wide, not tied to any one project. Use this for company-wide references: onboarding, policies, cross-team runbooks.
   * **Project** - linked to a specific project. Pick the project from the dropdown that appears. The space's page header will link back to that project, and it is the natural home for anything specific to that piece of work.
4. Add an optional **description** - it shows on the space's card and helps people scanning the list know what they will find inside.
5. Select **Create**.

{/* screenshot: the new-space dialog with name, type (global/project), and description fields */}

## Editing a space [#editing-a-space]

Open the **3-dot menu** on a space's card and select **Edit** to change its name and description at any time. A space whose name is auto-managed (see [Auto-generated spaces](#auto-generated-spaces) below) only lets you edit the description - its name stays in sync with the project.

### Visibility and who can see a space [#visibility-and-who-can-see-a-space]

If you can manage a space (you are a super-admin, or you hold edit rights on its owning project), the edit dialog also has a **visibility** section:

* **Everyone in the workspace** - any signed-in internal member can see the space, regardless of project membership.
* **Project members** (project-scoped spaces only) - visible to people who are members of the owning project, with document access according to their role.
* **Only specific members*&#x2A; - a hand-picked list. Choosing this reveals a search box: type a name to find and add someone, and remove anyone with the &#x2A;*×** on their chip. A restricted space starts visible only to whoever manages it until you add members.
* **Guests (external users) can see this space** - a separate checkbox. Leave it off to keep a space internal-only even when its visibility would otherwise let a guest see it.

Without manage rights, the edit dialog only offers the name and description - visibility stays whatever a manager last set.

{/* screenshot: the edit-space dialog with the visibility radio options and the restricted-member picker open */}

## Organising pages inside a space [#organising-pages-inside-a-space]

Inside a space, open it to see its page tree. Create pages, nest them under one another, and reorder them by dragging - the full page-level workflow (creating pages, smart links, comments, revisions, sharing, importing content) is covered in [Docs and wiki](/user-guide/knowledge/docs-and-wiki#creating-and-organising-pages).

Dragging in the tree reorders and reparents pages **within the same space**. There is currently no button to relocate a single page into a different space from the tree - if you want a page's content to live in another space instead, the practical route is to [duplicate](#duplicating-a-space) the whole space if you are moving a lot of it, or open the page's **copy as Markdown** action and paste the content into a new page in the target space for a single page.

## Duplicating a space [#duplicating-a-space]

Need a fresh copy of a space's structure - to reuse a well-organised knowledge base as a starting point for a new project, for example? Open the **3-dot menu** on a space's card and select **Duplicate**.

What you get:

* A new space named "&#x2A;(original name)* (copy)" with its own key, and every page from the original cloned with its title, content, and full parent-child hierarchy intact.
* The copy starts with the same visibility mode as the original, but if the original was restricted to specific members, the member list itself is **not** copied - the new space starts visible only to whoever manages it, so you consciously re-add the right people rather than inheriting a list that may not fit the new context.
* Comments, revision history, and attachments are **not** carried over - the copy is a clean starting point, not a full backup.

Duplicate is unavailable on [auto-generated spaces](#auto-generated-spaces) - there is only ever one per project, kept in sync automatically.

{/* screenshot: the space card's 3-dot menu with Edit, Duplicate, and Delete */}

## Deleting a space [#deleting-a-space]

From the same 3-dot menu, select **Delete** and confirm. This removes the space and every page inside it - there is no per-space undo, so check with a workspace administrator whether a recent [backup](/admin/operations/backup) exists before deleting something you are not sure about.

## Auto-generated spaces [#auto-generated-spaces]

Some spaces carry a small **sparkle** marker next to their name. These are created and kept up to date automatically (for example, a project's onboarding glossary) rather than by a person selecting **New space**. You can still edit the description and the pages inside stay fully user-editable, but the space's name follows its project and it cannot be duplicated or deleted independently of that project - it disappears when the project itself is deleted.

## Troubleshooting [#troubleshooting]

* **I don't see "New space".** You need to belong to at least one project (or hold a super-admin role) and not be an external/guest account.
* **I can't change a space's visibility, only its name and description.** Visibility is manager-only - you need edit rights on the owning project, or a super-admin role, to see those controls.
* **A restricted space is empty of members after I duplicated it.** This is expected - member lists never carry over on duplicate, precisely so a copy doesn't silently inherit access meant for a different context. Add the right people from the edit dialog.
* **A space's name field is greyed out.** It is an auto-generated space; its name follows its owning project. Rename the project to change it.
* **I want a page in a different space.** There is no direct move-to-another-space action in the page tree today - duplicate the space if you are relocating a lot of content, or copy a single page's Markdown into a new page in the target space.


# Docs and wiki (/user-guide/knowledge/docs-and-wiki)



Beyond tickets, orboto has a full **documentation** area for the knowledge that outlives any single task - specifications, how-tos, meeting notes, onboarding guides, and reference material. Open it from **Docs** in the sidebar.

## Spaces and pages [#spaces-and-pages]

Docs are organised into **spaces**. A space is a folder of related pages, shown as a tree you can nest.

* A space can be **global** (visible workspace-wide) or **linked to a project** (its natural home is that project, and the page header links back to it).
* Inside a space, each **page** is a rich document with a title, an optional emoji **icon**, and content written in the same editor as ticket descriptions.

{/* screenshot: the docs area with a space tree on the left and a page open on the right */}

### Creating a space [#creating-a-space]

1. On the Docs screen, select **New space**.
2. Name it, add an optional description, and choose whether it is global or linked to a project.
3. Save. You can filter the space list by scope and search spaces by name.

### Creating and organising pages [#creating-and-organising-pages]

1. Open a space and select **New page** (or the globe icon next to it to import one - see [Importing content](#importing-content) below).
2. Give it a title and pick an icon from the emoji picker if you like.
3. Write the content, then save.
4. **Move** or reorder pages within the tree by dragging, or nest one under another to build a hierarchy.
5. Use the filter box above the tree to jump to a page by name in a large space.

Each page carries a short **doc key** (for example `ACME-D12` for a project doc, or `DOC-5` for a global doc). Select the key to copy it - handy for referencing the page elsewhere.

On mobile the page tree becomes an off-canvas drawer opened with the menu icon; on desktop you can collapse it to a full-width reading surface and bring it back with the show-pages button.

## Smart links and backlinks [#smart-links-and-backlinks]

While writing, type `[[` to insert a **smart link** to another doc, ticket, project, or milestone. The link shows the target's current title and stays correct if the title changes.

Every page also has **backlinks** - a list of the other pages that link to it, shown at the bottom of the page - so you can see what references the page you are reading.

## Comments and revisions [#comments-and-revisions]

* **Comments** - select any text while reading a page and a small comment bubble appears; select it to open the comment composer anchored to that exact passage. Once resolved, a thread moves under **show resolved** and can be **reopened** later if needed.
* **Revisions** - every save is kept. Open the **revision history** to see a timestamped list, **preview** any earlier version side by side, and **restore** it if needed.

{/* screenshot: a doc page with an inline comment bubble and the revision history panel open */}

If you start editing and navigate away or close the tab before saving, orboto keeps a local draft and offers to **restore** it the next time you open the page - or you can discard it.

## Sharing and exporting [#sharing-and-exporting]

* **Visibility** - a page can be **public** (anyone with the link, no sign-in required), **workspace** (any signed-in member), **members** (only people with access to the space), or **specific** (a hand-picked list). Set it from the visibility dropdown while editing.
* When a page is public, a **share** button copies its public link to your clipboard.
* **Export** - download a page as **PDF** or **Markdown** from the download menu, or **copy the page as Markdown** straight from the toolbar (works in read mode, no need to enter edit mode first).

{/* screenshot: the doc visibility dropdown showing all four options */}

## Importing content [#importing-content]

Bring existing material into a space instead of retyping it:

* **From a URL** - select the globe icon next to New page, paste a URL, and orboto extracts the article content, converts it to Markdown, and saves it as a new page with a link back to the source.
* **From a file** - PDF, Word (`.docx`), Markdown, or plain text, up to 25 MB. Use the same import dialog's file tab, or the upload icon on an existing page to **upload as a new child page**, **replace** the current page's content (the old content is kept as a revision), or **append** the file's content to the end of the page.

## Attachments [#attachments]

Attach files to a doc page the same way you attach them to tickets. They are stored securely and served through the app, never as a public link.

## Ask AI about your docs [#ask-ai-about-your-docs]

If AI features are on, the **Ask AI** button (sparkle icon) on a doc lets you ask a question in plain language and get an answer drawn from your documentation, with references back to the source pages. This is the fastest way to find "what did we decide about X" without reading every page.

{/* screenshot: the Ask-AI panel answering a question with links to source doc pages */}

## The living wiki [#the-living-wiki]

orboto can maintain a **wiki** that keeps itself current as your work evolves - capturing decisions, summarising discussions, and flagging pages that have gone **stale** (out of date) so someone can refresh them. Where enabled, you will see a wiki badge and settings gear on the relevant spaces, and an **Ask** entry point. The heavy lifting (ingesting content, planning updates, lint checks) is handled by your workspace's automation and administrators; as a reader you mostly use **Ask** and follow the links it gives you. Pages the wiki maintains automatically are read-only for regular editing - they show a badge marking them as machine-maintained.

## Troubleshooting [#troubleshooting]

* **My changes disappeared after I navigated away.** Check for the draft-restore banner the next time you open the page - orboto buffers unsaved edits locally and offers to bring them back.
* **The smart link shows the old title.** Smart links resolve the current title live; if it still looks wrong, the target may have been deleted or you may not have access to it.
* **I can't find a delete or edit option.** Some pages (index, log, and source pages inside a wiki-managed space) are machine-maintained and read-only by design - look for the badge next to the title.
* **The public share link 404s for the recipient.** Confirm the page's visibility is actually set to **public** - the share button only appears once it is, but visibility can be changed back afterwards.


# Requirements documents (/user-guide/knowledge/requirements-documents)



orboto can turn a project into two polished, customer-facing documents:

* A **requirements specification** (a *Pflichtenheft*) - a structured, numbered document of what will be built, with must/should/could classification and a glossary.
* A **customer report** - a proposal or status overview of the project, its milestones and its budget.

Both are generated from the project you already have. The more of your project you have written down in the right places, the more complete these documents come out. This chapter explains exactly which piece of information fills which chapter, so nothing lands empty when you do not want it to.

> You need permission to generate these documents. If you cannot find the button described below, your workspace administrator has not granted it to you - that is expected, not a fault.

## Where you generate the documents [#where-you-generate-the-documents]

{/* screenshot: the customer report / requirements document builder dialog with the document-type and preset options */}

Open a project and select **Customer report** in the project's header. In the dialog that opens you choose the **document type** - a customer report or a requirements specification (Pflichtenheft) - and a few options (see [Options that shape the document](#options-that-shape-the-document) below). Then generate and download it as **PDF**, &#x2A;*Word (DOCX)**, or **Markdown**.

PDF and Word rendering can take a moment on a large project - you do not have to wait with the dialog open. It generates in the background and lands in the **Recent reports** list at the bottom of the dialog with a pending / ready / failed status; download it from there once it is ready.

## What a primer fact is [#what-a-primer-fact-is]

Several chapters are filled from **primer facts**. A primer fact is one small, structured piece of information about your project. Each fact has three parts:

* a **category** (for example *tech stack*, *non-functional*, or *other*),
* a **key** - a short label (for example `database` or `data protection`),
* a **value** - the information itself, written in plain words (for example `PostgreSQL 16 with pgvector`).

You capture primer facts once, and orboto reuses them: they help the AI assistant understand your project, and they fill the chapters of your requirements document and report. Think of them as the project's fact sheet.

An empty chapter in a generated document almost always means &#x2A;*"not captured yet"**, not a bug. The fix is to add the missing facts, not to change any settings.

## Which information fills which chapter [#which-information-fills-which-chapter]

This table shows, for the requirements specification, where every chapter gets its content. Fill the ones you care about and that chapter fills in.

| Chapter                     | Filled from                                                                                 | How you capture it                                   |
| --------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Objectives                  | The project's **description**                                                               | Edit the project description in project settings     |
| Current state               | Primer facts in category **conventions** or **other**                                       | Add primer facts (see below)                         |
| System overview             | Primer facts in category **tech stack**, **architecture**, **integrations**, **deployment** | Add primer facts                                     |
| Functional requirements     | Your **epics and tickets**                                                                  | Create real epics and tickets in the project         |
| Non-functional requirements | Primer facts in category **non-functional**                                                 | Add primer facts                                     |
| Solution outline            | Your **epics** and their summaries                                                          | Give epics a clear description or customer summary   |
| Scope                       | The list of functional requirements                                                         | Create real epics and tickets                        |
| Implementation and phases   | Your **milestones** and their dates                                                         | Create milestones with start/end dates and estimates |
| Acceptance criteria         | Derived from your requirements                                                              | Write clear, checkable ticket and epic titles        |
| Assumptions and cooperation | A standard note, plus primer facts in category **gotchas**                                  | Add primer facts for known constraints               |
| Glossary                    | Primer facts in category **other**                                                          | Add glossary terms as primer facts                   |

The customer report draws on the same project data - your milestones, epics, tickets and budget - so the same capture work improves both documents.

A couple of things worth knowing:

* The **glossary** and the **current state** chapters both draw on the *other* category. If you want a clean glossary, put state-of-the-world facts under *conventions* and keep *other* for genuine glossary terms.
* The **acceptance criteria** chapter is built from your requirements rather than a separate field, so clear, verifiable ticket and epic titles pay off directly here.

## Worked examples: capturing your facts [#worked-examples-capturing-your-facts]

### Your technology stack [#your-technology-stack]

Capture each part of your stack as a **tech stack** fact - these fill the system overview chapter.

* key `database`, value `PostgreSQL 16`
* key `backend`, value `Node.js API`
* key `frontend`, value `React web application`

### Your non-functional requirements [#your-non-functional-requirements]

Non-functional requirements are the qualities the system must have - performance, security, data protection, operations, languages - as opposed to specific features. Capture each as a **non-functional** fact. These lead the non-functional chapter and are shown exactly as you wrote them.

* key `performance`, value `Search results return in under one second for typical projects`
* key `security`, value `All access is permission-controlled; sign-in supports two-factor authentication and single sign-on`
* key `data protection`, value `Personal data can be exported and deleted on request, in line with the GDPR`
* key `languages`, value `The interface is available in English and German`

If you have no non-functional facts yet, orboto still tries to derive some from your other facts by looking for relevant keywords - but the explicit facts you write are always the clearest and are shown first.

### Your glossary [#your-glossary]

Capture project-specific terms your customer might not know as **other** facts. Each becomes a glossary entry.

* key `Milestone`, value `A phase of the project with its own goal and date`
* key `Epic`, value `A large piece of work grouping several smaller tickets`

## How to capture primer facts [#how-to-capture-primer-facts]

{/* screenshot: the project settings AI primer tab with the list of primer facts and the add-fact form */}

1. Open the project and go to its **settings**.
2. Select the **AI primer** tab.
3. Use **Add fact**: pick a category, type a short key and the value, and save.
4. To fix a fact later, edit it in the same place; to replace a wrong one, use **supersede** so the history is kept.

Workspace administrators can also add facts that apply to **every** project (organisation-wide rules) from the admin area. Use those sparingly.

> The AI assistant can add primer facts for you too. If you have it enabled, you can simply ask it to record a fact - for example "add a non-functional fact that search must return in under a second" - and confirm the change. See [AI assistant](/user-guide/ai-assistant).

## Options that shape the document [#options-that-shape-the-document]

When you generate a document you can adjust:

* **Document type** - a customer report or a requirements specification (Pflichtenheft).
* **Report type** (customer report only) - &#x2A;*Scope (proposal)**: milestones and epics, no progress or status; or &#x2A;*Status (progress)**: all non-private tickets with progress.
* **Outline** (requirements specification only) - **Neutral** (a balanced default), **Industry** (chapter order per VDI/VDE 3694, for industrial systems), or **Software** (SRS chapter order per IEEE 830). These reorder and rename chapters; the content is the same.
* **Sections** (customer report only) - toggle individual chapters on or off: project overview, milestones, epics, tickets, budget/pricing, and (when AI is on) an AI-written executive summary.
* **Pricing** - show effort in **hours** (estimates), in **money** at your customer rate (needs budget permission), or as a **lump sum** - a flat amount, currency, and optional note you type in.
* **Options** - show or hide assignee names, and show or hide ticket keys, in the output.
* **AI enhancements** (when AI is on) - an AI-written **executive summary**, and **translate content** into the document's language.
* **Language** - the document's output language, independent of your own interface language.

Once you have a combination you like, **save it as a named configuration** so you can re-generate the same document later - for a status update, or for a second customer on a similar project - in one click via **Apply**, without resetting every option.

Whatever you choose, anything marked **private** - private milestones, private tickets, and their contents - is always left out of the document.

## Must, should, could [#must-should-could]

In the requirements specification, each functional requirement is tagged **must**, **should**, or **could**. That tag comes straight from the ticket's **priority**: high-priority work becomes *must*, normal becomes *should*, low becomes *could*. So if the must/should/could split matters to your customer, set your ticket priorities deliberately before you generate the document.

## Keeping customer wording clean [#keeping-customer-wording-clean]

The document never shows your raw internal ticket descriptions - those can contain planning notes you would not send to a customer. For each epic and ticket, orboto uses, in order: a **customer summary** if you wrote one, otherwise a short AI-written summary of the description (when AI is enabled), otherwise just the title. For the cleanest result, fill in the **customer summary** field on the epics and tickets that will appear in the document.

## Troubleshooting [#troubleshooting]

* **A whole chapter is empty.** Almost always means "not captured yet" - check the [chapter table](#which-information-fills-which-chapter) above for what feeds it and add the missing primer facts, epic summaries, or milestone dates.
* **I don't see the requirements-specification option, only customer report.** Generating a Pflichtenheft needs a separate permission from the customer report. Ask your workspace administrator.
* **Money pricing is missing.** Showing effort in money needs budget-view permission on the project, in addition to the document-generation permission.
* **My PDF/Word never showed up.** Check **Recent reports** in the dialog for a **Failed** status - reopen the dialog later; large projects can take a while to render.
* **The output is in the wrong language.** The **Language** option controls the document's language independently of your own interface language - set it explicitly per document.

## Where to go next [#where-to-go-next]

* Set up projects, milestones, epics and tickets: [Projects and tickets](/user-guide/work/projects-and-tickets)
* Let the assistant capture facts for you: [AI assistant](/user-guide/ai-assistant)
* Plan phases and dates: [Planning and alerts](/user-guide/planning/planning-and-alerts)


# Search (/user-guide/knowledge/search)



orboto has one search box that reaches everything you are allowed to see - tickets, docs, and comments. Open it from the **Search** button in the centre of the top bar, or press **Cmd/Ctrl + K** anywhere.

{/* screenshot: the global search palette open with a query and grouped results */}

## Quick search [#quick-search]

Start typing (at least two characters) and results appear grouped by kind, with the matching ticket or doc key shown alongside the title. Use the **All / Tickets / Docs / Comments** tabs to narrow by type. Select a result - or use the arrow keys and Enter - to jump straight to it.

* The palette remembers your **recent** searches so you can re-run them with one click from an empty query.
* If your search returns nothing, orboto may offer a &#x2A;*"did you mean"** suggestion for a likely typo - select it to re-run the corrected query.
* If a plain search comes up empty and AI is available on your workspace, orboto silently retries it as an AI search behind the scenes - so a phrase like "my bugs from last week" can still return something even if you never switched modes.

## Precise search with the query language [#precise-search-with-the-query-language]

For exact, repeatable filtering, switch on **OQL** (the code-brackets toggle) next to the search box. This lets you write a short query in orboto's query language instead of clicking through filters:

{/* screenshot: the search palette in query mode with an OQL expression and a result count */}

```
project = ACME AND assignee = currentUser() AND statusCategory != done
ORDER BY priority DESC
```

Press **Enter** to run it (OQL doesn't search as you type - the parser cost isn't worth paying per keystroke). A few ready-made **presets*&#x2A; (for example, "Guest tickets") are one click away, and the &#x2A;*?** button opens an inline reference of fields, operators, and functions without leaving the palette. Errors show inline with the line and column where the query broke.

The full field and operator reference, with worked examples, lives on the [OQL reference page](/api-cli/oql).

## Saving a search [#saving-a-search]

Turn a query you use often into a reusable **saved search**:

1. Run a search (plain or OQL).
2. Select **Bookmark** (in OQL mode) or **Save** (on the full search page) and give it a name.
3. It is now available to run again in one click from the search page's saved-search list, and can be pinned to your [dashboard](/user-guide/everyday/dashboard) as a live widget.

## AI search (natural language) [#ai-search-natural-language]

If your workspace has AI features on, switch to **AI mode** (the sparkle toggle) and describe what you want in plain language, for example "high priority bugs assigned to me that are overdue." orboto turns that into a set of filters, runs it, and shows the matching tickets - combining exact filtering with **semantic** matching (finding tickets that mean the same thing even when they use different words).

{/* screenshot: the search palette in AI mode with a natural-language question, its results, and the detected-filter chips */}

* The filters orboto extracted (project, status, priority, assignee, labels, date range, ...) show as **chips** above the results. Remove a chip's `×` to drop just that filter and re-run without it.
* If nothing matched with the filters applied, orboto automatically falls back to an unfiltered keyword search and tells you so; if even that comes up empty it may fall back further to **semantically similar** tickets.
* Select **Edit in OQL** under the chips to see - and fine-tune - the exact OQL query the AI produced.

## The full search page [#the-full-search-page]

For a roomier results view with pagination - useful for long result lists - open the dedicated **Search** page. It offers the same plain/AI modes and type filter as the palette, plus your list of saved searches with a delete option for each.

## Troubleshooting [#troubleshooting]

* **My query returns nothing but I expect matches.** In OQL mode, check the inline error for a line/column - a typo'd field name or a missing quote is the most common cause. In plain mode, remember results are ACL-filtered: you only ever see what you have permission to see.
* **AI mode returns different results than I expect.** Check the filter chips - the AI may have narrowed by a project, assignee, or date range you didn't intend. Remove the offending chip, or switch to OQL to write the exact filter yourself.
* **I don't see the AI toggle.** AI search is only available when your workspace has AI features configured and enabled for your account.
* **A ticket or doc I know exists isn't showing up.** Private tickets and private milestones are excluded unless you have access; guest and external accounts see an even narrower slice by design.


# The LLM-Wiki (/user-guide/knowledge/wiki-quality)



A normal [doc space](/user-guide/knowledge/doc-spaces) only changes when someone opens a page and edits it. The **LLM-Wiki** is an optional mode you can turn on for a space that keeps it current on its own: new material you feed it gets folded into the right pages automatically, questions get answered with citations back to the source pages, and the space periodically checks its own pages for problems - a page nobody has touched while newer material has arrived, two pages that quietly contradict each other, a page nothing links to. This chapter covers that whole loop: turning it on, feeding it knowledge, asking it questions, and keeping the result trustworthy.

> Everything on this page needs AI configured for your workspace (see [AI providers and models](/admin/ai/ai)) and the LLM-Wiki turned on for the specific space you are working in.

## Turning it on for a space [#turning-it-on-for-a-space]

Open a space and, if you can manage it, select the **settings gear** next to the space name in the page tree sidebar.

{/* screenshot: the LLM-Wiki settings modal with the enable checkbox, apply mode, and lint schedule */}

1. Tick **Enable the LLM-Wiki on this space**.
2. Choose the **apply mode**:
   * **Review gate** (the default) - when new material is curated into pages, the proposed changes wait for an administrator to approve them before they land.
   * **Auto-apply** - curated changes write straight to the pages, no approval step.
3. Choose the **lint schedule** - how often the space checks itself for issues (see [Wiki lint](#wiki-lint) below): **on demand only**, **weekly**, or **daily**.
4. Optionally set up **ingest sources** (see [Recording knowledge](#recording-knowledge-what-feeds-the-wiki) below): an email routing key and sender allowlist, and a note on the web clipper.
5. Save.

Once enabled, the space shows a small **LLM-Wiki** badge next to its name so everyone opening it knows it is self-maintaining.

## Recording knowledge: what feeds the wiki [#recording-knowledge-what-feeds-the-wiki]

The wiki never writes itself from nothing - it curates **source material** you bring in. Every source lands as its own page (tagged **source**), and if the space's LLM-Wiki is enabled, an automatic worker reads it and proposes how to fold it into the space's pages: update an existing page that already covers the topic, or create a new one for something genuinely new. Under **auto-apply** that update happens right away; under **review gate** it waits for an administrator to approve it.

Ways to bring material in:

* **Paste a URL or upload a file** - the same import flow as any doc space, covered in [Docs and wiki](/user-guide/knowledge/docs-and-wiki#importing-content). In a wiki-enabled space, whatever you import becomes a source the curation worker then processes.
* **Email it in** - once an administrator sets an **email routing key** in the space's settings, mail sent to `wiki+<key>@` your workspace's inbound mail address lands as a source automatically. A **sender allowlist** (specific addresses, or a bare domain to allow everyone on it) controls who is allowed to feed the space this way - an empty allowlist means nobody can, so this is opt-in per space.
* **Clip a web page** - install the orboto browser clipper extension, paste in an API key, pick the target space, and select **Send to orboto** on any page you are reading to send it in as a source.
* **Turn an answer into a page directly** - see [Save an answer to the wiki](#asking-the-docs) below; this skips the source-and-curate step and writes a page immediately.
* **Write a page yourself** - a wiki-enabled space is still a normal doc space underneath; you can always create and edit pages by hand exactly as described in [Docs and wiki](/user-guide/knowledge/docs-and-wiki#creating-and-organising-pages).

### Reading the page types [#reading-the-page-types]

Inside a wiki-enabled space you will see a small icon next to some pages' titles, marking a page the automation manages rather than a page a person wrote directly:

* **Source** - raw imported material, kept as a record of what came in.
* **Index** - the space's own table of contents, used internally to check whether every page is properly linked.
* **Log** - a running activity record of what the automation has done.

These three kinds are **read-only** by design - editing them by hand would fight the automation. Regular pages (no icon) are the curated wiki content itself, and stay fully editable like any other doc page.

{/* screenshot: a wiki space's page tree with the source/index/log icons next to a few pages */}

## Asking the docs [#asking-the-docs]

The **Ask AI** panel (the sparkle icon) beside a doc page lets you ask a question in plain language and get an answer drawn only from pages you can read, with numbered citations linking back to the exact source pages - hover a citation for a preview without leaving the panel. This is the fastest way to find "what did we already decide about X" without reading every page yourself. The full mechanics (how a question is typed, where the panel lives) are in [Docs and wiki](/user-guide/knowledge/docs-and-wiki#ask-ai-about-your-docs); this section covers what is happening underneath and what you can do with the answer.

Each answer also tells you, implicitly, how confident to be in it: orboto tries a fast **keyword** match first, falls back to **semantic** matching (finding pages that mean the same thing even in different words) when keywords come up short, and combines both as **hybrid** when that gives the best result. An answer with strong citations across multiple pages is more trustworthy than a thin one with a single weak match - always check the citations rather than taking the prose at face value.

If an answer is good enough to keep, select **Save to wiki** underneath it. Give the page a title (or keep the suggested one, based on your question) and save - orboto creates a proper wiki page with the answer's content and smart-links to everything it cited, or updates the same page if you save an answer to that exact question again later. This is the quickest way to turn a one-off question into durable, reusable knowledge.

{/* screenshot: the Ask AI panel with an answer, its citation chips, and the Save to wiki button */}

## Staleness detection [#staleness-detection]

A wiki page does not go stale just by sitting still - most reference material is meant to stay true for a long time. orboto only flags a page as **possibly stale** when both of these are true: the page has not been touched in over 90 days, **and** newer source material has arrived in the space since then that the page has not been updated to reflect. A page nobody has fed anything new never gets flagged, no matter how old it is - "stale" means "the world moved and this page didn't," not "this page is old."

Staleness is one of the checks [wiki lint](#wiki-lint) runs - see below for where flagged pages show up and how to resolve them (refresh the page's content, or dismiss the flag if it does not actually need a change).

## Wiki lint [#wiki-lint]

**What it is.** A self-audit that scans a wiki-enabled space for six kinds of problem and lists them as **issues** you can act on. Nothing is changed automatically - lint only reports; you decide what, if anything, to do about each issue.

| Issue                       | What it means                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Orphan page**             | Nothing links to this page and it is not listed in the space's index - readers have no way to find it by browsing.      |
| **Missing cross-reference** | A page's text mentions another page's title by name but never actually links to it.                                     |
| **Stale page**              | Untouched for 90+ days while newer source material has arrived - see [Staleness detection](#staleness-detection) above. |
| **Unprocessed source**      | A source document was imported but the curation worker has not turned it into wiki content yet.                         |
| **Contradiction**           | Two pages appear to say conflicting things about the same topic.                                                        |
| **Undocumented concept**    | Your source material repeatedly references something that has no dedicated page yet.                                    |

Contradiction and undocumented-concept checks use AI directly and only run when AI is configured; the other four are checked mechanically and always run.

### Where issues appear [#where-issues-appear]

* **The space sidebar** shows a small badge with the open-issue count next to a **Lint issues** section; expand it to see the list, and select the refresh icon to **run lint now** rather than waiting for its schedule.
* **A doc page's header** shows a pill with its own open-issue count whenever the page you are currently reading has one or more open issues - hover it to read what they are.
* **The admin LLM-Wiki inbox** (see below) lists issues across every wiki space in the workspace in one place.

{/* screenshot: the space sidebar's Lint issues panel expanded, with a couple of issues listed */}

### Resolving an issue [#resolving-an-issue]

Each issue carries a plain-language **message** and, where possible, a **suggested fix** (for example, "add a smart-link to this page" or "re-ingest recent sources to refresh this page"). Read the suggestion, make the change it describes if it makes sense, and:

* **Dismiss** an issue you have looked at and decided is not worth acting on (an intentional orphan page kept as a private note, for example) - it will not be reported again unless the underlying problem changes.
* Do nothing and re-run lint later - if the condition that caused the issue is no longer true (you linked the page, updated the stale content), the next lint run automatically marks it **fixed** on its own; you never have to close an issue by hand once you have actually addressed it.

### The admin inbox [#the-admin-inbox]

Workspace administrators have a dedicated **LLM-Wiki** page (under **Admin**) with two tabs:

* **Issues** - every lint issue across every wiki-enabled space, filterable by status (**open**, **dismissed**, **fixed**), with the same dismiss/reopen controls as the per-space panel plus which space each issue belongs to.
* **Audit** - a log of every automated edit the wiki's curation worker has made (what operation, which space, a content hash before and after), exportable as a **CSV** for a full paper trail of what the automation changed and when.

A small usage line at the top of the page shows the current month's ingest and lint run counts against your plan's limits, so administrators can see usage at a glance without digging through billing.

{/* screenshot: the admin LLM-Wiki inbox with the Issues tab open, status filter, and the Audit tab's CSV export button */}

## Troubleshooting [#troubleshooting]

* **I don't see a settings gear on my space.** You need manage rights on the space (the same permission that gates other space-management actions) - ask a project admin or a super-admin to enable the LLM-Wiki for you, or to grant you that permission.
* **I imported a source but nothing changed on any page.** Under review-gate apply mode, curated changes wait for an administrator to approve them rather than landing immediately - ask whether one is pending. Also check that the space actually has the LLM-Wiki enabled; a plain doc space keeps imported material as a static page and never curates it.
* **I can't edit a page.** Check for the source/index/log icon next to its title - those three kinds are machine-maintained and read-only by design. Edit the regular (unmarked) wiki pages instead.
* **A page I know is out of date isn't flagged stale.** Staleness only fires when newer source material has arrived since the page last changed - if nothing new has been fed into the space, orboto has no signal that the page needs a refresh. Feed in an updated source, or edit the page directly.
* **Lint shows an issue I've already fixed.** Lint only re-checks when it runs - either wait for its scheduled run or select **Run lint now** in the space sidebar to re-check immediately.
* **Email ingest rejects my message.** The space's sender allowlist is empty by default (nobody allowed) until an administrator adds your address or your domain to it.


# Absences (/user-guide/planning/absences)



Open **Absences** in the sidebar. It has three tabs: **Mine** (your own requests and balance), **Approvals** (requests waiting on you), and **Team** (a shared calendar of who's off).

{/* screenshot: the absences page Mine tab with balance cards and the request list */}

## Requesting time off [#requesting-time-off]

1. On the **Mine** tab, select **Request** - or shift-click a day on the [Time Calendar](/user-guide/planning/time-tracking#time-calendar) to open the request pre-filled with that date.
2. Choose the **type** (for example vacation or sick leave - the list is configured by your administrator).
3. Set the **from** and **to** dates, and an optional note.
4. Submit.

Duration is counted in **working days only** - weekends, public holidays, and company closures are excluded automatically, so a Friday-to-Monday request costs two days, not four. Your **Mine** tab shows three balances for the year: **total**, **used**, and **remaining** days.

A request still in **pending** or **draft** status can be cancelled (the trash icon on its row). Once it's **approved** or **rejected**, it's final - ask your approver to reject and let you resubmit if the dates were wrong.

### Importing an external calendar [#importing-an-external-calendar]

If your vacations already live in another calendar app, select **Import .ics** on the Mine tab to upload an `.ics` file. orboto parses each event and reports how many were **created** vs. **skipped** (for example, duplicates it already has), plus any warnings, before you leave the import dialog.

## Approving time off [#approving-time-off]

If you approve absences for your team, the **Approvals** tab lists every pending request with the requester, dates, and day count. **Approve** it with one click, or **Reject** with a required reason - the requester sees that reason on their own Mine tab.

{/* screenshot: the approvals tab with pending requests and approve/reject actions */}

## The Team calendar [#the-team-calendar]

The **Team** tab is a month grid: one row per person, one column per day, with a colored bar for each approved absence (color follows the absence type) spanning its date range. Weekends are shaded, and you can navigate month to month. Hover a bar to see the type and exact dates.

{/* screenshot: the team calendar month grid with colored absence bars per person */}

## Effect on capacity [#effect-on-capacity]

Approved absences automatically reduce the person's [capacity](/user-guide/planning/capacity) for the days they cover - there's nothing to configure, it flows through the same working-day calculation.

## For administrators [#for-administrators]

Absence **types**, **public holidays**, and **company closures*&#x2A; are configured in the admin area's absence settings (three tabs: Types, Holidays, Closures). Company closures also support the same **.ics import** as personal absences, so an office-wide closure calendar can be uploaded in one step instead of entered day by day. Each user's yearly **allowance** (including carry-over days) is set on their profile in the admin Users page.

## Troubleshooting [#troubleshooting]

**My request shows the wrong number of days.** Check for public holidays or company closures inside your date range - they're excluded automatically and won't count, even though the calendar shows the full span you picked.

**I can't cancel a request.** Only **pending** or **draft** requests can be cancelled by you. An approved or rejected request needs your approver to act (reject an approved one, or let you resubmit after a rejection).

**A teammate is missing from the Team calendar.** The Team calendar shows every approved absence workspace-wide to any internal user (unlike [Capacity](/user-guide/planning/capacity), which scopes to shared projects) - if they're not appearing, their request likely isn't **approved** yet, or falls outside the month you're viewing.


# Capacity planning (/user-guide/planning/capacity)



Capacity answers "can we actually do all this in the time planned?" - it compares each person's available working time against what's assigned to them and what they've actually logged.

## How capacity is computed [#how-capacity-is-computed]

Each member has a **work schedule** (working days and hours per day), editable per user from their profile in the admin area. From that, orboto derives available hours for any date range you pick.

Non-working time is subtracted automatically: weekends, public holidays, company closures, and approved absences all reduce capacity. This is the same **blocked-days** source that drives the Time Calendar, so the two views never disagree with each other.

## Reading the view [#reading-the-view]

Open **Capacity** in the sidebar.

{/* screenshot: the capacity table with capacity, assigned, logged and utilisation columns */}

1. Pick a **range**: 1, 2, 4, or 12 weeks starting from the current week.
2. For each person, the table shows:
   * **Capacity** - available hours for the range, with blocked days (holidays, closures, absences) called out separately, e.g. `160h (−2d)`.
   * **Assigned** - the sum of estimates on every open (not-done) ticket currently assigned to them, across projects you can see - not limited to the selected range.
   * **Logged** - actual time entries recorded inside the range.
   * **Utilization** - logged hours as a percentage of capacity, color-coded: green under 50% (room to spare), yellow in the healthy middle, red over 100% (overbooked).
3. Expand a row (the chevron) to see the person's logged hours broken down **per project** - useful when someone is overbooked and you need to know which project to pull work from.

**Who you can see.** A super-admin sees every active user. Everyone else sees only people who share at least one project with them - capacity is scoped to your own visibility, never the whole workspace.

## Acting on it [#acting-on-it]

* Rebalance by reassigning tickets or moving due dates for anyone showing red.
* If someone is systematically overbooked, set up a **User Over Capacity** alert rule so you're notified automatically instead of having to check the page - see [Milestones and alerts](/user-guide/planning/planning-and-alerts#alerts).

## Troubleshooting [#troubleshooting]

**Someone's capacity looks lower than expected.** Check the `(−Nd)` marker next to their capacity figure - it means N working days in the range are blocked by a holiday, company closure, or an approved absence. That's expected, not a bug.

**A person is missing from the table entirely.** You only see people who share a project with you (unless you're a super-admin). If you expect to see them, confirm you're both members of at least one common project.

**Assigned hours look too high or too low.** Assigned sums the **estimates** on every open ticket assigned to the person right now, regardless of the date range you picked - it is not scoped to the window like Logged is. A ticket with no estimate contributes nothing to this column even if work is happening on it, and a closed (Done) ticket drops out of the sum entirely.


# Critical path (/user-guide/planning/critical-path)



The **critical path** is the longest chain of dependent tasks in a plan - the chain that determines the earliest a project can possibly finish. Any task on that chain that slips pushes the whole finish date back by the same amount. Every task *not* on that chain has some amount of **slack** (also called float): room to run late without affecting the finish date, because something else is already the limiting factor.

**A small example.** Say a project has two paths: `ACME-1 → ACME-2 → ACME-3`, three tickets that must happen in order and together take 6 days, and a separate ticket `ACME-4` that takes 2 days and isn't blocked by anything. The project can't finish before day 6, no matter how fast `ACME-4` goes - so `ACME-1`, `ACME-2`, and `ACME-3` are the critical path, each with zero slack, while `ACME-4` has 4 days of slack: it could start up to 4 days late and still not be the reason the project runs over.

This technique - working out the longest chain and how much slack everything else has - is called the **Critical Path Method** (CPM). orboto computes it automatically from your ticket dependencies.

## What you need before this is useful [#what-you-need-before-this-is-useful]

Critical path is only meaningful once a project has:

* **Dependencies** between tickets - use the "blocks / blocked by" relationship in a ticket's [Dependencies section](/user-guide/work/tickets#dependencies). Without any dependencies, there's no chain to compute.
* **Estimates** on tickets - used to size how long each ticket occupies in the schedule (see below for what happens without one).

## How orboto turns estimates into a schedule [#how-orboto-turns-estimates-into-a-schedule]

CPM needs a duration for every ticket. orboto converts each ticket's **estimate** into working days at 8 hours per day, and rounds up to at least 1 day - so even an unestimated ticket still occupies a one-day slot in the schedule rather than vanishing from it entirely. All the scheduling math works in whole working-day units; turning those into actual calendar dates (skipping weekends and holidays) is the Gantt's job.

For each ticket, orboto computes four numbers, all as working-day offsets from the start of the window being scheduled:

* **ES / EF** (Earliest Start / Earliest Finish) - the soonest the ticket could start and finish, found by walking forward from its dependencies.
* **LS / LF** (Latest Start / Latest Finish) - the latest it could start and finish without delaying the project, found by walking backward from the finish date.

**Slack** (or float) is the gap between those: `LS - ES`. A ticket with zero slack is on the critical path - any delay there delays everything after it. A ticket with slack can run that many days late without changing the finish date.

## Where to see it [#where-to-see-it]

### Gantt view [#gantt-view]

Open a project's **Gantt** view and select **Critical path** in the toolbar. With it on:

* Tickets on the critical path are highlighted (a red outline on the bar).
* Hovering a bar shows either "critical (0 slack)" or "slack: N day(s)".
* Dependency arrows on the critical path are drawn in red and full opacity; everything else fades so the chain that matters stands out.

{/* screenshot: the Gantt view with Critical path toggled on, showing the highlighted chain and a slack tooltip */}

The same milestone filter you use elsewhere on the Gantt scopes the critical-path calculation too - turn it on to see the critical path for just one milestone's tickets, with dependencies pointing outside that milestone ignored rather than breaking the calculation.

### Network diagram [#network-diagram]

Select the **Network** icon in the view switcher to open the **Network diagram** - a node-and-edge layout with one box per ticket, positioned by dependency order, showing the full CPM detail directly:

* Each box shows the ticket's key, title, and duration in days.
* **ES**, **EF**, **LS**, and **LF** are printed in the box's corners.
* A **slack N** or **critical** label sits in the middle, colored green for slack and red for critical.
* Edges (dependency arrows) between critical-path tickets are drawn thicker and in red; others are thin and grey.
* Pan by dragging, zoom with the scroll wheel or the zoom buttons, and use **Fit to view** to frame everything at once.

{/* screenshot: the Network diagram with several ticket boxes, their ES/EF/LS/LF grid, and the critical path in red */}

Like the Gantt, the Network diagram respects the project's current milestone filter.

## Deadline-aware float [#deadline-aware-float]

By default, slack is measured against the whole project's finish date - so a chain that finishes well before the last ticket looks comfortably relaxed, even if it has its own hard due date it's actually going to miss. orboto accounts for this: each ticket's **effective deadline** is the earlier of its own due date and its milestone's due date (whichever is tighter), and that deadline feeds into the same backward pass that computes LS/LF.

When a chain can't realistically meet that deadline, its slack goes **negative** - it's already behind, not just tight - and every ticket on that chain is flagged as a **deadline risk**. Both the Gantt and Network views highlight these tickets in red, with a summary badge like "3 deadline risks · worst 2d behind" and a tooltip on the affected ticket giving the exact due date and the shortfall in working days. A ticket with a comfortable deadline (later than the schedule would already deliver it) is unaffected - its slack is unchanged.

## Dependency cycles [#dependency-cycles]

CPM has no answer for a cyclic dependency (ticket A blocks B, which blocks A). If your dependencies contain a cycle, orboto can't compute a critical path at all - instead of a highlighted chain, both the Gantt and the Network diagram report the cycle directly, naming the tickets tangled in it, and note that the critical path is undefined until it's broken. Remove one of the dependencies in the cycle and the calculation resolves immediately.

## What you're allowed to see [#what-youre-allowed-to-see]

The critical path respects the same visibility rules as everything else in a project: you need to be a project member, private tickets you can't see (and any dependency edges touching them) are excluded from the calculation, and external guests only see tickets in milestones they've been given access to. The path and slack figures you get always reflect only the tickets you're allowed to see - not the project's full dependency graph if it's bigger than your view of it.

## Troubleshooting [#troubleshooting]

**The Critical path toggle doesn't seem to do anything.** It only has something to highlight once tickets have dependencies on each other - a project with no "blocks / blocked by" links has no chain to compute. Add dependencies first.

**A ticket I expected to be critical shows slack instead.** Check whether it's missing a dependency that should connect it to the real chain, or whether an unrelated, longer chain elsewhere in the project is the actual constraint - the critical path is always the *single longest* chain, not every chain that looks important.

**The Network diagram shows a cycle message instead of a path.** Two or more tickets depend on each other in a loop. The message names the tickets involved - remove one dependency between them to break the cycle.

**A ticket's slack looks too generous given its due date.** Confirm the due date is actually set on the ticket (or its milestone) - slack is only deadline-aware for tickets with an effective deadline; without one, slack is measured against the project's overall finish date instead.

**An unestimated ticket is taking up more schedule time than I expected.** Every ticket occupies at least one working day in the schedule, even with no estimate recorded - add an estimate if you want its duration to reflect actual expected effort instead of the one-day floor.


# Milestones and alerts (/user-guide/planning/planning-and-alerts)



This chapter covers milestones - the checkpoints that structure a project's timeline - and alert rules, which watch your work and warn you when something needs attention. For releases and reusable project blueprints, see [Versions and releases](/user-guide/work/versions) and [Project templates](/user-guide/work/templates).

## Milestones [#milestones]

A **milestone** is a meaningful checkpoint in a project - a phase, a sprint, or a deliverable that groups tickets toward a shared goal and date. Milestones are managed from a project's **Settings → Milestones** tab, and used all over the app: filters, the Gantt view, analytics, and guest access.

{/* screenshot: the milestones tab in project settings with drag-to-reorder rows */}

### Creating and editing a milestone [#creating-and-editing-a-milestone]

1. Open **Settings → Milestones** and select **New milestone**.
2. Enter a **name** and optional **start** / **end** dates.
3. Save.

Select the pencil icon on a milestone row to edit its name, dates, and privacy afterwards. **Drag a row** by its grip handle to reorder milestones - the order you set here is the order they appear everywhere else (filters, the Gantt view, dropdowns).

* Each milestone has a **status**: `active`, `completed`, or `archived`, changeable from the row's dropdown.
* A milestone can be marked **private** so only people with the `milestone:view_private` permission see it.
* Milestones carry a short **key** (for example `ACME-M3`) for unambiguous reference in comments, docs, and links.
* **Show closed milestones** (checkbox above the list) reveals archived/completed ones when you need to look back; they're hidden by default to keep the list focused on current work.
* Assign tickets to a milestone (from the ticket detail panel, or in bulk) so their progress rolls up to it.

### Deleting a milestone [#deleting-a-milestone]

Deleting a milestone does not delete its tickets - they become unassigned from that milestone. There is no undo, so if you only meant to close it out, set its status to `completed` instead.

## Alerts [#alerts]

**Alert rules** watch your work and warn you when something needs attention - a budget nearing its limit, a ticket stuck too long, a deadline at risk, a timesheet not submitted. Open **Alerts** in the sidebar for workspace-wide rules, or a project's **Settings → Alerts** tab for rules scoped to just that project.

{/* screenshot: the alerts page with the Active, Rules and History tabs */}

### Active alerts and history [#active-alerts-and-history]

* The **Active** tab lists alerts currently firing, each with the rule name and a short summary. Select **Resolve** to mark one handled.
* The **History** tab shows past alerts and when they were resolved.

### Creating an alert rule [#creating-an-alert-rule]

Select **New rule** to open the four-step wizard:

1. **Trigger** - pick what to watch for (see the table below) and a name for the rule.
2. **Conditions** - the trigger-specific settings, for example a threshold percentage, which statuses count as "open", or how many days out to start warning.
3. **Notification** - choose **severity** (info, warning, critical), whether it notifies **in-app** and/or by **email**, which roles or members get notified, and a **cooldown** in minutes so a recurring problem doesn't spam you every time it's checked.
4. **Review** - confirm before creating.

| Trigger                 | Fires when                                                                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Budget Threshold        | The project's burn-rate crosses the threshold percent.                                                            |
| Milestone Deadline Risk | A milestone's completion is below threshold AND its end date is within the lookahead window.                      |
| Ticket Overdue          | An open ticket is past its due date by N days.                                                                    |
| Estimate Exceeded       | Logged time on a ticket crosses N% of its estimate.                                                               |
| User Over Capacity      | A user's assigned hours exceed their weekly capacity by N%.                                                       |
| Ticket Stuck            | A ticket hasn't changed status for N days.                                                                        |
| No Sprint Activity      | An active milestone has had no ticket updates for N days.                                                         |
| Timesheet Not Submitted | A closed period still has unsubmitted timesheets after N days.                                                    |
| Milestone AI Risk       | An active milestone reaches red on the AI risk assessment (open %, blocked tickets, days remaining, budget burn). |
| Ticket Created          | A ticket is created - narrow it by milestone, the creator's project role, or whether the creator is a guest.      |

Once created, a rule's row lets you:

* **Test rule** - see how many tickets/entities would match right now, before you switch it on.
* **Mute** - silence the rule for 1 hour, 24 hours, 7 days, or forever, without deleting it.
* Toggle **Active** on or off.
* **Delete** the rule.

When an alert fires it also reaches you through your normal [notifications](/user-guide/everyday/notifications) (in-app and/or email, per the rule's settings), and the cooldown keeps orboto from re-notifying you about the same firing alert on every check.

## Troubleshooting [#troubleshooting]

**A milestone I archived still shows in the ticket filter.** Turn on **Show closed milestones** in the filter bar to see it, or leave it off to hide archived/completed milestones from day-to-day views.

**My alert rule never fires.** Use **Test rule** first - it shows exactly what would match right now, which is the fastest way to tell a wrong condition from a rule that's simply waiting for the right moment. Also check the rule is **Active**, and that it isn't currently **muted**.

**I'm not getting emailed for a firing alert.** Confirm the rule has **Notify by email** enabled in its Notification step, and that you're in its notified roles/members list - in-app and email are independent toggles.


# Time tracking (/user-guide/planning/time-tracking)



orboto records the time you spend on work under the **Time** group in the sidebar: **Time Calendar** and **Timesheets**. A running stopwatch also lives in the top bar so you can start and stop timing from anywhere. Requesting time off has its own page - see [Absences](/user-guide/planning/absences) - and team-wide workload is covered in [Capacity planning](/user-guide/planning/capacity).

> Timesheets are for internal team members. Guest and external users see only the Time Calendar, and only if it has been enabled for them.

## The stopwatch (timer) [#the-stopwatch-timer]

The **timer** in the top bar is the quickest way to track effort as it happens.

{/* screenshot: the running timer widget in the top bar with pause and stop controls */}

* **Start** a timer on a ticket (from the ticket, or by claiming work). The elapsed time counts up in the top bar.
* **Pause / resume** when you step away.
* **Stop** when you finish - orboto writes the elapsed minutes as a **time entry** against that ticket, using the note you set when you started.

Only one stopwatch runs at a time. If you start timing a second ticket, orboto commits the time on the first one before switching, so nothing is lost.

## Time Calendar [#time-calendar]

The **Time Calendar** shows a week at a time, one column per day, with your logged time laid out as blocks so you can see where your hours went and fill any gaps.

{/* screenshot: the Time Calendar week view with logged time blocks and the overlay strip */}

### Logging and planning time [#logging-and-planning-time]

The calendar has two ways to add something to a slot, picked by the **Time entry / Plan block** toggle in the header:

* **Click** an empty slot for a quick add at that hour, or **click and drag** to sweep out an exact start time and duration.
* With the toggle on **Time entry**, this logs actual time against a ticket right away.
* With the toggle on **Plan block**, it books a slot ahead of time without logging anything yet - useful for blocking your calendar before the work happens. Open a plan block and select **Convert to entry** to turn it into a real, logged time entry once the work is done (it needs a ticket assigned first - edit the block to add one if it doesn't have one yet). A converted block becomes read-only.
* **Shift+click** a slot to open an absence request pre-filled with that day - see [Absences](/user-guide/planning/absences).

Either dialog asks for the **project**, **ticket**, **date**, **duration**, and an optional **note**. Existing blocks can be **dragged** to move them or **resized** from either edge to change their duration.

You can edit or delete an entry later, as long as it isn't part of an already-**approved** timesheet (see below).

### Reading the calendar [#reading-the-calendar]

* Your work-hours window is shaded, and the grid auto-scrolls to it when you open the page.
* Non-working days and blocked days (public holidays, company closures, approved absences) are shaded and hatched.
* Each day header shows your **logged vs. goal** hours for the day, turning green once you've hit your target.
* Use the **zoom** control to make the grid more compact or roomier.
* If you're an administrator, a **View as** picker lets you inspect another user's logged time (their plan blocks stay private).

### The context overlay [#the-context-overlay]

Toggle **Context** to show a strip above the grid with your current **milestones** (as spanning bars), **version releases**, and **ticket due dates** for the visible week - so you can see what's due while you plan your time. Narrow it to specific projects with the project filter next to the toggle.

### Calendar settings [#calendar-settings]

The gear icon opens:

* **Recurring time-entry templates** - save a frequently used entry (project, ticket, duration, note, and a recurrence pattern) and insert its next occurrence as a plan block with one click instead of retyping it.
* **Subscribe feed** - a personal, read-only calendar URL (webcal/ICS) you can add to an external calendar app. Choose what it includes: absences, ticket due dates, milestones, and timesheet deadlines. Regenerate the URL at any time to invalidate the old one.

{/* screenshot: the calendar settings dialog with recurring templates and the subscribe-feed URL */}

## Timesheets [#timesheets]

A **timesheet** is your logged time for a period (for example a month), gathered up for approval. Open **Timesheets** in the sidebar; the **Mine** tab is generated automatically from your time entries, no manual step required.

{/* screenshot: the timesheets list showing periods with their status */}

1. Select a period to open its **detail** view - every entry, grouped by date, project, and ticket.
2. While the timesheet is **open** (or **rejected**), select any entry to edit it inline, or edit it from the Time Calendar.
3. Select **Submit** to send it for approval. Its status moves to **submitted**, then to **approved** or **rejected**.
4. If **rejected**, the reason is shown so you can correct the entries and resubmit.
5. Once **approved**, every entry in it is locked - you can no longer edit or delete them, from either the timesheet or the Time Calendar.

If you approve timesheets, the **Pending** tab lists everyone's submitted timesheets waiting on you, with **Approve** or **Reject** (with a required reason) on each row. Select **PDF** on any timesheet, yours or a team member's, to download a formatted export.

## Troubleshooting [#troubleshooting]

**I can't edit a time entry.** It's locked into an approved timesheet. Ask your approver to reject the timesheet (with a reason) if the entry genuinely needs correcting - that reopens it for editing.

**My drag on the calendar created the wrong thing.** Check the **Time entry / Plan block** toggle in the header before you drag - it decides what a click-and-drag gesture produces, and it's remembered across sessions.

**The subscribe feed isn't showing new events in my calendar app.** Most external calendar apps cache a webcal/ICS feed and refresh it on their own schedule (often hourly), not instantly - give it time, or manually refresh the subscription in that app.

**A plan block won't disappear after I logged the real time.** Open it and select **Convert to entry** instead of logging a separate time entry - deleting the block just discards the plan without logging anything, and a converted block can't be deleted afterwards (it's now the real entry).


# Approval gates (/user-guide/work/approvals)



An **approval gate** (also called a sign-off gate) is a rule that says: before a piece of work can move into a particular state, a specific person or group has to say yes. It's a common pattern wherever a status change has real consequences - releasing something to customers, closing a ticket that was disputed, moving a change into production - and a team doesn't want that step to happen just because someone dragged a card across a board.

**An example.** ACME's team wants every ticket to require the release manager's sign-off before it can be marked "Released". Without a gate, anyone who can edit a ticket could set that status directly. With a gate configured on "Released", the move is blocked until the release manager - or whoever the policy names - approves it.

## How this relates to statuses [#how-this-relates-to-statuses]

[Statuses](/user-guide/work/workflows-and-statuses) in orboto don't have a fixed sequence by default - any status is reachable from any other. Approval gates are the actual, project-configurable way to restrict a move: a gate targets **one destination status** and blocks entry into it until the required sign-off lands. It doesn't care which status the ticket is coming from.

## Setting up an approval policy [#setting-up-an-approval-policy]

Open a project's **Settings → Approvals** tab. This tab only appears for users with the `ticket:manage_approvals` permission - it's not just disabled without it, it's not shown at all.

{/* screenshot: the Approvals tab with a list of policies and the "Add policy" button */}

Select **Add policy** to open the policy editor:

* **Name** and **Description** - free text, shown in the policy list and on the ticket's approval panel.
* **Requires approval to enter** - the destination status this gate protects. Required.
* **Milestone (optional)** - narrow the gate to tickets in one milestone; leave as **Any milestone** to apply project-wide.
* **Ticket type (optional)** - narrow the gate to one ticket type (bug, task, story, epic, improvement); leave as **Any type** to apply to all.
* **Mode**:
  * **Any N approvers** - the request is approved once a set number of distinct people approve; a single reject rejects the whole request. Set **Required approvals** to the number needed.
  * **Sequential steps** - each step needs exactly one approval, in order; a reject at any step rejects the whole request.
* **Active** - untick to keep a policy defined but not currently enforced.
* **Approvers** (labeled **Eligible approvers** in Any N mode, &#x2A;*Approval steps (in order)** in Sequential mode) - add one or more entries, each pointing at:
  * a project **Role** (anyone holding it is eligible),
  * a specific **User**, or
  * a **RACI role** on the ticket itself (Accountable, Responsible, Consulted, or Informed) - useful when "whoever is Accountable on this ticket" should approve, whatever ticket it turns out to be.

Save. The policy list shows each policy's name, a one-line summary ("Enter *Released* · Sequential · 2 approver(s)"), and an **Inactive** badge on any policy you've turned off. Deleting a policy doesn't erase history - any approval requests it already created keep their record.

{/* screenshot: the policy editor with target status, mode, and the approver-steps list */}

**More specific policies win.** If a ticket matches more than one active policy for the same destination status (for example, a project-wide policy and a milestone-specific one), the more specific one applies: milestone + type beats milestone alone, which beats type alone, which beats a plain project-wide policy.

## What happens when a ticket hits a gate [#what-happens-when-a-ticket-hits-a-gate]

When someone tries to move a ticket into a gated status - from the ticket detail panel or by dragging it on the board - and no approved request already exists, the move is blocked. An error appears explaining that the transition requires approval and that a sign-off request is now pending, and the ticket stays where it was.

At the same time, an **Approvals** panel appears on the ticket (it's invisible on tickets with no approval activity, so most tickets never show it) with:

* Which status is being requested and which policy triggered it.
* A status chip: **Pending**, **Approved**, **Rejected**, **Cancelled**, or **Applied**.
* A progress line, e.g. "1 of 2 approvals" (and, in Sequential mode, which step is next).
* The votes cast so far, each with an optional comment.

{/* screenshot: the Approvals panel on a ticket, showing progress and the approve/reject buttons */}

Eligible approvers - the people the policy actually names - see a comment box and **Approve** / **Reject** buttons directly in that panel. The person who requested the move can't approve their own request; that's a deliberate separation-of-duties rule, not a bug. The requester (or anyone with `ticket:manage_approvals`) can **Cancel** a still-pending request instead.

### After a request is fully approved, you re-issue the move [#after-a-request-is-fully-approved-you-re-issue-the-move]

Approval doesn't automatically apply the transition. Once a request reaches **Approved**, the panel says so and tells you to set the status again - repeat the exact same move you originally tried, and this time it finds the already-approved request and applies it, marking the request **Applied** so it can never be replayed for a later move into the same status.

## Bypassing a gate [#bypassing-a-gate]

A super-admin can push a gated transition through even without the required sign-off - an emergency escape hatch. Doing so is recorded in the [audit log](/admin/operations/audit-log) as a bypass, so it stays on the record even though it skipped the normal approval flow. Ordinary project members and admins cannot bypass a gate; the bypass is reserved for the workspace's super-admin role.

## Troubleshooting [#troubleshooting]

**I don't have an Approvals tab in Project Settings.** You need the `ticket:manage_approvals` permission - ask a project admin to grant it, or to make the change on your behalf.

**My status move is blocked and I don't see why.** Check the Approvals panel on the ticket - if a gate applies, a pending request explains what's needed. If there's no approval activity at all, the block is more likely a permission issue or an [open blocker](/user-guide/work/workflows-and-statuses#what-actually-restricts-a-move) rather than an approval gate.

**The request shows Approved but the ticket still hasn't moved.** That's expected - re-issue the same status change once more to apply it. Approval clears the way; it doesn't perform the move by itself.

**I can't approve a request on my own ticket.** Requesters can't approve their own requests, even if they're otherwise eligible under the policy. Ask another eligible approver, or use **Cancel request** if the move was a mistake.

**Deleting a policy didn't remove its history.** That's intentional - past approval requests keep their record (who requested it, who approved, when) even after the policy that created them is edited or deleted, so the audit trail stays intact.


# Portfolio views (/user-guide/work/portfolio)



A **portfolio** is a named group of projects - a program, a customer engagement, a product line - that you build on purpose and then read as a single rollup dashboard. It is an admin-managed surface: creating and editing portfolios requires a portfolio-management permission that an administrator grants, separate from being a member of the underlying projects.

{/* screenshot: the portfolios list with project counts per card */}

## Creating a portfolio [#creating-a-portfolio]

1. Open **Portfolios** (under the admin area).
2. Select **New portfolio**.
3. Give it a **name** (for example "Q3 Customer Program") and an optional **description**.
4. Tick the **projects** that belong to it from the checklist. A project can belong to more than one portfolio.
5. Save.

Edit a portfolio at any time to add or remove projects, or rename it. **Deleting** a portfolio only removes the grouping - the projects themselves, and everything in them, are untouched.

## Reading the dashboard [#reading-the-dashboard]

Select **Open dashboard** on a portfolio card to see its rollup.

{/* screenshot: the portfolio dashboard with the RAG summary, progress, effort and Earned Value tiles */}

The top row of tiles summarizes the whole portfolio:

* **Health** - a count of projects in each RAG state: red, amber, green, or unknown (not enough data to judge).
* **Progress** - tickets done vs. total, across every visible project.
* **Effort** - hours logged so far and hours remaining, summed from ticket estimates and time entries.
* **Earned Value** - **SPI** (schedule performance index) and **CPI** (cost performance index) averaged across projects that have an EVM baseline set. A value under `0.95` is flagged in red. Projects with no baseline are excluded and shown separately as "No EVM baseline set".

If any project in the portfolio has a budget configured, a **budget rollup** table breaks spend down by currency: budget, actual cost, and projected cost (projected cost is flagged when it exceeds the budget).

### At-risk milestones [#at-risk-milestones]

A dedicated panel lists every milestone across the portfolio that is either **overdue** or **due soon**, with how many of its tickets are still open. This is the fastest way to see what is about to slip before it does.

{/* screenshot: the at-risk milestones panel with overdue and due-soon badges */}

### Per-project breakdown [#per-project-breakdown]

Below the summary, a table lists every project in the portfolio with its RAG status, progress percentage, SPI, CPI, milestone counts (overdue milestones are called out), and the **signals** that drove its RAG rating - so a red project is never a black box.

{/* screenshot: the per-project RAG table with signals column */}

### Exporting [#exporting]

Use **Export CSV** to download the current rollup as a spreadsheet for a status report or a meeting deck.

## Visibility [#visibility]

Every figure is filtered to the projects you are actually a member of (or can see as an administrator) - the same access rules as everywhere else in orboto. If the portfolio contains projects you cannot see, a banner tells you how many are hidden and makes clear that every number on the page only ever aggregates the ones you can. There is no separate reporting database to go stale: the dashboard reads the same live data as each project's own analytics.

## Troubleshooting [#troubleshooting]

**I don't see Portfolios in the admin area.** Creating and viewing portfolios needs a permission an administrator grants (separate from project membership). Ask an administrator to grant it if you manage cross-project reporting.

**A project I expect is missing from the rollup.** Either it was never added to the portfolio (edit the portfolio and tick it), or you are not a member of it - check the hidden-projects banner at the top of the dashboard.

**Earned Value shows "No EVM baseline set".** SPI/CPI need a budget baseline configured on the project first; see [Analytics](/user-guide/analytics) for setting one up.


# Projects and tickets (/user-guide/work/projects-and-tickets)



This is the heart of orboto: where work lives. A **project** is a container for related work. Inside it, each unit of work is a **ticket**. This page covers finding your projects, the five ways to view a project's tickets, filtering, and a project's settings. For creating and working a single ticket, see [Working with tickets](/user-guide/work/tickets).

## Working with projects [#working-with-projects]

### Finding your projects [#finding-your-projects]

Select **Projects** in the sidebar to see every project you are a member of. Each project has a short **key** (for example `ACME`) that prefixes its tickets, so ticket `ACME-42` belongs to the project with key `ACME`.

{/* screenshot: the projects list showing project cards with keys */}

### Pinning a project [#pinning-a-project]

If you spend most of your time in one project, you can **pin** it. Once pinned, selecting **Projects** in the sidebar takes you straight to that project instead of the list. Use the pin / unpin control on the project page to change this.

### Creating a project [#creating-a-project]

If you have permission to create projects:

1. On the Projects screen, select **New project**.
2. Give it a name and a key. The key is what prefixes every ticket in this project - pick something short and stable, since renaming it later changes how every existing ticket reference reads.
3. Save. You can refine its settings afterwards (see [Project settings](#project-settings-a-quick-tour)) or start it from a [template](/user-guide/work/templates) instead of blank.

## Viewing a project's tickets [#viewing-a-projects-tickets]

Open a project and you get five ways to look at the same tickets. Switch between them with the view buttons at the top of the project.

{/* screenshot: the project view switcher with Kanban, List, Gantt, Network and RACI */}

### Kanban board [#kanban-board]

The **Kanban** board shows tickets as cards in columns, one column per **status** (for example To Do, In Progress, Done). Drag a card from one column to the next to move the work forward.

{/* screenshot: the Kanban board with cards in status columns */}

**Showing hidden columns.** Your administrator can mark some statuses as "hidden on the board by default" to keep the board tidy. When a project has such statuses, a **Show hidden columns** toggle appears above the board (it shows how many tickets are tucked away). Turn it on to reveal those columns, and **Hide hidden columns** to tidy up again. Your choice is remembered on this device.

### List [#list]

The **List** view is a compact table. Use it when you want to scan many tickets, sort them, or group them:

* **Group by** - cluster rows by milestone, status, assignee, and so on.
* **Sort by** - order rows by the field you care about.

For quick capture, the List view also offers an inline **quick-add** row - type a title and press Enter to create a ticket without opening the full form.

### Gantt [#gantt]

The **Gantt** view is a timeline. Each ticket is a bar placed by its start and due dates, so you can see what runs when and where things overlap. Dependencies between tickets are drawn as links between the bars. See [Milestones and alerts](/user-guide/planning/planning-and-alerts) for scheduling with milestones, and [Versions and releases](/user-guide/work/versions) for release planning.

### Network [#network]

The **Network** view draws tickets as a diagram of their **dependencies** - which ticket blocks which. It is the quickest way to spot a chain of blockers or the critical path through the work.

### RACI [#raci]

The **RACI** view is a responsibility matrix. RACI stands for **Responsible** (does the work), **Accountable** (owns the outcome), **Consulted** (gives input), and **Informed** (kept in the loop). This view shows, per ticket, who holds each of those roles, so accountability is never ambiguous.

{/* screenshot: the RACI matrix mapping people to tickets */}

## Filtering and finding tickets in a project [#filtering-and-finding-tickets-in-a-project]

Above the board is an **avatar row** for filtering by assignee - select one or more team members to see only their tickets - plus the **filter bar**:

* Filter by **type** (task, bug, story, epic), **priority**, **milestone**, **version**, or **label**.
* Choose **No milestone** to find unscheduled work, or **Show closed milestones** to include finished ones.
* **Clear** resets every filter at once.

{/* screenshot: the filter bar with the assignee avatar row and type/priority/milestone/label filters */}

If you manage guest access, a **guest view** toggle lets you preview the project exactly as an external user would see it.

## Project settings: a quick tour [#project-settings-a-quick-tour]

If you have permission to manage a project, the **Settings** button opens its configuration:

* **Members** - who is in the project and their role. You can also **invite** new members.
* **Statuses / workflow** - the columns on the Kanban board, including which are hidden by default.
* **Labels** - colored tags you attach to tickets.
* **Milestones** and **versions** - see [Milestones and alerts](/user-guide/planning/planning-and-alerts) and [Versions and releases](/user-guide/work/versions).
* **Budgets** - a money and/or hours budget for the project and its milestones (see [Analytics](/user-guide/analytics)).
* **Alerts** - project-scoped alert rules (see [Milestones and alerts](/user-guide/planning/planning-and-alerts#alerts)).
* **Guest access** - whether external users can see the project, and which milestones are open to them (see [Customers and guests](/user-guide/customers-and-guests)).

{/* screenshot: the project settings page showing the members and workflow tabs */}

## Troubleshooting [#troubleshooting]

**A ticket I expect to see is missing from the board.** Check the filter bar and the assignee avatar row first - an active filter is the most common cause. If the ticket belongs to a closed milestone, turn on **Show closed milestones**; if it has no milestone at all, clear the milestone filter or select **No milestone**.

**I can't find New project.** Creating projects needs a permission an administrator grants - ask them, or ask to be added as a member of an existing project instead.

**The Kanban board looks emptier than the List view for the same project.** A status your administrator hid by default is likely holding tickets - toggle **Show hidden columns** above the board.


# RACI roles (/user-guide/work/raci)



**RACI** is a way of writing down, explicitly, who does what on a piece of work - instead of leaving it implied by who happens to be assigned. The name is an acronym for four roles:

* **R**esponsible - does the work.
* **A**ccountable - owns the outcome and signs off on it. Exactly one person, always.
* **C**onsulted - gives input before a decision is made (two-way).
* **I**nformed - kept in the loop after the fact (one-way).

The point of RACI is avoiding the classic failure mode where three people are "kind of" assigned to something and each assumes someone else has final say. Naming exactly one Accountable person ("one throat to choke") forces that ambiguity out into the open.

**A small example.** Say ticket `ACME-42`, "Migrate billing to the new payment provider," involves two engineers doing the actual work, an engineering lead who has to sign off before it ships, a security reviewer whose input is needed beforehand, and an account manager who just needs to know when it's live. In RACI terms: the two engineers are **R**, the lead is **A**, the security reviewer is **C**, and the account manager is **I**.

## How this maps onto orboto [#how-this-maps-onto-orboto]

RACI in orboto is an **optional layer on top of assignees**, not a replacement for them:

* **R** and **A** together are exactly the ticket's existing **assignees** - anyone you assign to a ticket already has one of those two roles.
* **C** and **I** are new: an advisory layer that doesn't change who's assigned, but does change who gets notified and who's expected to weigh in.

## Turning RACI on for a project [#turning-raci-on-for-a-project]

RACI is **off by default** per project. Open **Settings → General** and check **Enable RACI roles** (requires `project:edit`).

{/* screenshot: the "Enable RACI roles" checkbox and its explanatory text in Project Settings */}

While it's off, the ticket detail panel shows the plain multi-assignee picker and there's no RACI view in the project - zero extra surface for projects that don't want it. Turning it on switches every ticket's people-picker into the role editor described below, and adds a **RACI matrix** view to the project's view switcher.

## Setting roles on a ticket [#setting-roles-on-a-ticket]

Once RACI is enabled, open a ticket and look at its **RACI** section (where the assignee picker used to be). Each person on the ticket shows as a row: a colored single-letter badge (A/R/C/I), their avatar and name, and - if you have the `ticket:manage_raci` permission - a dropdown to change their role and a remove button.

* **Add a person** using the search box at the bottom (&#x2A;*Add person…**); they're added as Responsible by default, and you can change that afterward.
* **Change a role** from the dropdown next to their name.
* **Remove** a person with the button next to their row.

Rows are always shown Accountable first, then Responsible, Consulted, Informed.

{/* screenshot: the RACI role editor on a ticket, with role badges and the add-person search box */}

### The single-Accountable rule [#the-single-accountable-rule]

At most one person can hold **A** on a ticket, and orboto enforces this on the server, not just in the UI. Trying to make a second person Accountable is rejected with an error naming who currently holds it. To hand accountability to someone else, change the current Accountable's role first (to R, C, or I, or remove them), then set the new person to A.

### The "awaiting consulted input" hint [#the-awaiting-consulted-input-hint]

If anyone on the ticket holds **C*&#x2A;, a small amber hint appears: &#x2A;*"Awaiting consulted input."** This is a reminder, not a gate - orboto doesn't block you from closing a ticket just because a Consulted person hasn't commented. If your team needs a hard requirement like that, an [approval gate](/user-guide/work/approvals) can require sign-off from a specific RACI role before a ticket enters a given status.

### Where it shows up elsewhere [#where-it-shows-up-elsewhere]

A ticket with an Accountable person shows a small **A** badge on its Kanban card, so you can spot ownership without opening the ticket. Anywhere else a ticket's assignees are listed, RACI-enabled tickets carry the full role breakdown alongside them.

## The RACI matrix [#the-raci-matrix]

Once RACI is enabled, a grid icon appears in the project's view switcher (next to Kanban, List, Gantt, and Network) - select it to open the **RACI matrix**: rows are tickets, columns are project members, and each cell shows that person's role on that ticket.

{/* screenshot: the RACI matrix with tickets as rows, members as columns, and role cells */}

* **Filter by milestone** - the dropdown at the top defaults to all milestones.
* **Epics only** - narrows the rows to epic-type tickets, useful for a high-level ownership review.
* **Filter members** - a text box that narrows the columns by name.
* Cells are **editable in place** (with the same permission as the ticket-level editor) - pick a role directly from the matrix instead of opening each ticket.
* Select a ticket's row to open it.
* **Export** the current view (respecting your filters) as **CSV** or **PDF** - the format a status deck or a PMO report typically wants.

If you land on the matrix for a project that hasn't enabled RACI, it shows a short explanation instead of an empty table, pointing you back to the Settings toggle.

## Notifications [#notifications]

Marking someone **Informed** puts them on the ticket's notification list, exactly the way being an assignee does - they'll be notified of changes according to their own [notification preferences](/user-guide/everyday/notifications) (for example, whether "ticket status changed" notifications are on for them). Removing the **I** role takes them off that list.

## Permissions [#permissions]

Setting or changing RACI roles requires &#x2A;*`ticket:manage_raci`**, a permission separate from general ticket editing - so a workspace can let a lead or PMO own responsibility assignment without giving them full ticket-edit rights, or restrict who can reassign accountability. By default, any role that has ticket-edit rights also has this one, so nothing changes for existing roles until an admin deliberately narrows it. Reading a ticket's RACI roles and the matrix follows the same visibility as the ticket itself - no separate permission is needed just to look.

## Troubleshooting [#troubleshooting]

**I don't see the RACI matrix icon in the view switcher.** RACI hasn't been enabled for this project - a project admin turns it on in Settings → General.

**I can't change anyone's RACI role.** You need the `ticket:manage_raci` permission; without it you see roles read-only.

**I tried to make someone Accountable and got an error.** Someone else already holds it - the error names them. Change or remove their role first, then set the new Accountable.

**A Consulted person hasn't responded and I want to close the ticket anyway.** That's allowed - Consulted is advisory only. If you need it to be a hard requirement, set up an [approval gate](/user-guide/work/approvals) that requires the Consulted role's sign-off before the ticket can enter that status.


# Project templates (/user-guide/work/templates)



A template is a reusable project blueprint. Instead of rebuilding the same milestone plan, label set, and starter tickets every time you kick off a similar engagement, you build the structure once and **apply** it whenever you need it.

{/* screenshot: the templates gallery with template cards, apply and export buttons */}

## What a template contains [#what-a-template-contains]

* **Milestones** - each with a name and **relative day offsets** (start +N days, end +M days) instead of fixed calendar dates.
* **Starter tickets** - a title and type, optionally pointed at one of the template's milestones.
* **Labels** - name and color.
* **Doc pages** - starter documentation pages.

A template never contains operational data - no time entries, comments, or file attachments. Because milestone dates are relative offsets, applying the same template in March or in November produces sensible dates either way.

## Creating a template [#creating-a-template]

Open **Templates** in the sidebar, then either:

* **New** - select **New template**, give it a name, optional description, and category, and it opens in the template editor to fill in.
* **From an existing project** - snapshot a project you like into a template. Only its structure is copied.

In the editor, add milestones (name + start/end offset in days), tickets (title, optionally linked to a milestone), labels (name + color), and doc pages one row at a time - each add/remove happens immediately, so there is no separate save step.

{/* screenshot: the template editor with milestone, ticket, label and doc-page sections */}

**Personal vs. global.** A new template is personal to you by default. Tick **Make global** (at creation, or from the template's card) to share it with the whole workspace.

**Export / import.** Use the export icon on a template card to download it as a JSON file, and **Import** at the top of the Templates page to bring one in - handy for moving a template between workspaces or keeping one under version control.

## Applying a template [#applying-a-template]

1. Select **Apply** on a template card.
2. Pick the target **project** and a **start date**.
3. Review the **preview** table - it shows each milestone's computed start and end date for the start date you chose.
4. Confirm. orboto creates the milestones with absolute dates, the starter tickets (linked into the right milestone), the doc pages, and matches labels **by name** against the target project - existing labels are reused, missing ones are created.

The confirmation reports exactly how many milestones, tickets, labels, and doc pages were created, so you can sanity-check the result immediately.

{/* screenshot: the apply-template dialog with project picker, start date and milestone preview table */}

## Tips [#tips]

* Keep one template per engagement type (client project, game jam, release train) and refine it after each project retrospective - templates are cheap to iterate on since applying never touches the original.
* Offsets can overlap - parallel milestones (for example "Design" and "Prototyping" running at the same time) are fine.
* Use **Export** on a template you are happy with as a lightweight backup before making experimental changes to it.

## Troubleshooting [#troubleshooting]

**Applying the template didn't create the labels I expected.** Labels are matched by exact name. If a target project already has a label with a slightly different name (different casing, trailing space), you'll end up with two similar labels instead of one being reused - clean up names before applying, or clean up duplicates in [project settings](/user-guide/work/projects-and-tickets#project-settings-a-quick-tour) afterwards.

**A milestone date looks wrong after applying.** Check the offset value in the template editor, not the applied project - offsets are always counted in calendar days from the start date you entered when applying, including weekends.

**I can't find a template a colleague made.** Personal templates are only visible to their creator; ask them to toggle **Make global**, or export and send you the file to import.


# Working with tickets (/user-guide/work/tickets)



A ticket is a single unit of work inside a [project](/user-guide/work/projects-and-tickets). This page covers creating one, everything you can do inside its detail panel, changing many tickets at once, and the editor they all share.

## Creating a ticket [#creating-a-ticket]

1. In a project, select **New ticket**.
2. Enter a **title**. Optionally set the **type**, **priority**, **milestone**, **version**, and an **estimate** (how long you expect it to take).
3. Add a description using the rich-text editor (see [Writing with the editor](#writing-with-the-rich-text-editor)).
4. Save.

For quick capture, the List view offers an inline **quick-add** row - type a title and press Enter to create a ticket without opening the full form.

{/* screenshot: the new-ticket form with title, type, priority and milestone fields */}

## Working inside a ticket [#working-inside-a-ticket]

Select any ticket card or row to open the **ticket detail** panel. This is where most day-to-day work happens.

{/* screenshot: the ticket detail panel with description, sidebar fields and the comment thread */}

### Editing the basics [#editing-the-basics]

* **Title and description** - select to edit in place. The description uses the rich-text editor.
* **Status** - move the ticket to another status without going back to the board.
* **Priority, type, milestone, version** - set from the ticket's sidebar.
* **Assignees** - add one or more people responsible for the ticket. Tickets support multiple assignees.
* **Start and due dates** - set the schedule; these feed the Gantt view and deadline alerts.
* **Estimate** - record how long you think the ticket will take; this feeds [capacity planning](/user-guide/planning/capacity).
* **Private** - mark a ticket private so only people on its access list can see it.

### RACI on a ticket [#raci-on-a-ticket]

Beyond assignees, you can set the **RACI** roles (Responsible, Accountable, Consulted, Informed) directly on a ticket. These roll up into the project's RACI view.

### Comments [#comments]

Discuss the ticket in the **comment thread*&#x2A; at the bottom. Comments use the rich-text editor, so you can format text, paste images, and **@mention** teammates to notify them. You can edit or delete your own comments, and a comment's **revision history** lets you see earlier versions of an edited comment.

### Checklists [#checklists]

Break a ticket into smaller steps with a **checklist**. Add a new checklist, then add items and tick them off as you go.

* A checklist item can be **linked to another ticket**. When it is, the item ticks and un-ticks automatically as that linked ticket's status changes - handy for tracking sub-work.
* If a checklist grows into real work items, you can **convert** it into proper sub-tickets in one step.

{/* screenshot: a checklist on a ticket with some items ticked and one linked to another ticket */}

### Sub-tickets and parents [#sub-tickets-and-parents]

A ticket can have a **parent** and **children**. Use this to break an epic into smaller tickets, or to nest a task under a story. The ticket panel shows the parent link and lists any children.

### Dependencies [#dependencies]

Record that one ticket **blocks** or is **blocked by** another. Dependencies drive the Gantt links, the Network view, and blocked-ticket warnings on your dashboard.

### Attachments [#attachments]

Attach files (images, documents, and so on) to a ticket. Attachments are stored securely and downloaded through the app - there are no public links.

### Sharing a ticket [#sharing-a-ticket]

The **share** menu on a ticket lets you:

* **Copy the ticket key** (for example `ACME-42`).
* **Copy a link** to the ticket.
* **Copy as Markdown** - a formatted snippet with the title, status, priority, assignees, and more, ready to paste into a document or chat.
* **Email** a summary of the ticket.

### Activity and Git [#activity-and-git]

* The **Activity** tab shows the ticket's history - what changed, when, and by whom.
* The **Git** tab shows linked commits and pull requests when your workspace connects a code repository (see [Integrations](/integrations)). Mentioning a ticket key in a commit message links it here automatically.

### AI actions on a ticket [#ai-actions-on-a-ticket]

If your workspace has AI features enabled, an **AI menu** on the ticket offers help such as:

* **Summarize** the ticket and its discussion.
* **Suggest** a better title, labels, or priority.
* **Estimate** how long the ticket will take, based on similar past tickets.
* **Split** a large ticket into suggested smaller ones.
* **Ask** a question about the ticket and get an answer grounded in its content.

Related and possible-duplicate tickets are also surfaced automatically while you work, so you do not open the same thing twice. The AI never changes anything without you confirming it. See [AI assistant](/user-guide/ai-assistant) for the workspace-wide chat.

## Bulk actions [#bulk-actions]

Need to change many tickets at once? Turn on **select mode**, tick the tickets you want, and use the **bulk actions** bar that appears:

* **Set status**, **set priority**, **set milestone**, **set version**, or **set due date** for all selected tickets.
* **Add an assignee** to all of them.
* **Delete** the selected tickets (with a confirmation).

{/* screenshot: several tickets selected with the bulk actions bar showing set-status and set-milestone */}

## Writing with the rich-text editor [#writing-with-the-rich-text-editor]

Descriptions, comments, and doc pages all use the same editor. You can:

* Format text (bold, italic, headings, lists, quotes, code).
* Paste or drag in images.
* **@mention** teammates.
* Insert a **smart link** by typing `[[` and picking a ticket, project, doc, or milestone - the link stays live and shows the current title.
* Switch to raw **Markdown** with the toolbar toggle if you prefer to type the markup yourself.

## Troubleshooting [#troubleshooting]

**I can't move a ticket to a status I know exists.** Some workflows restrict which status transitions are allowed (for example, you can't skip straight from To Do to Done). Move it through the intermediate status, or ask a project admin if the workflow needs adjusting.

**A checklist item keeps un-ticking itself.** It's linked to another ticket and mirrors that ticket's status - close (or reopen) the linked ticket instead of toggling the checklist item directly.

**I deleted several tickets by mistake with bulk actions.** Bulk delete asks for confirmation but has no undo. Check with a project admin whether a recent [backup](/admin/operations/backup) can restore them; going forward, filter down to exactly the set you mean to change before selecting all.

**The AI menu doesn't appear on a ticket.** AI features are enabled per workspace by an administrator - if it's missing everywhere, ask whether AI is configured; if it's missing on one ticket only, it may be private and the AI actions may not have access.


# Versions and releases (/user-guide/work/versions)



A **version** models a release of your product - a name and a target **release date**, with tickets assigned to the version they ship in. Versions are managed from a project's **Settings → Versions** tab.

{/* screenshot: the versions list in project settings with status badges and progress bars */}

## Creating a version [#creating-a-version]

1. In a project, open **Settings → Versions** and select **New version**.
2. Enter a **name** (for example `v1.2.0`) and a **release date** - both required.
3. Save.

A version's **status** moves through `draft`, `active`, `released`, and `archived` as work progresses; each version also shows a live progress bar of tickets done vs. total.

## Assigning tickets [#assigning-tickets]

Set a ticket's version from the ticket detail panel, or in bulk from the List view's [bulk actions](/user-guide/work/projects-and-tickets#bulk-actions). Assigning a version to a ticket that has **no due date** automatically sets the due date to the version's release date - the release becomes the deadline by default.

## Rescheduling: the date cascade [#rescheduling-the-date-cascade]

Change a version's **release date** (in Settings → Versions, or on the [version overview](#the-version-overview) page) and, if any of its tickets carry a due date, orboto shows a cascade warning before committing:

1. Edit the release date and select save.
2. A yellow warning box tells you how many tickets have a due date and would move.
3. **Confirm** shifts every one of those tickets' due dates by the same number of days as the release date, in one atomic operation. Tickets without a due date are left alone.
4. **Cancel** backs out without changing anything.

If no ticket in the version has a due date, the release date updates immediately with no cascade prompt.

**Releasing** a version (the **Mark released** button) records the actual release as a fact for that moment - it never reschedules anything, even if the release date and today's date differ.

## The version overview [#the-version-overview]

Select a version's name to open its overview page: the same progress bar and release-date editor as the settings tab, plus every ticket in the version **grouped by status** so you can see at a glance what's still open. Select any ticket to open it directly from here.

{/* screenshot: the version overview page with tickets grouped by status column */}

## Troubleshooting [#troubleshooting]

**Changing the release date didn't move any tickets.** The cascade only shifts tickets that already have a due date. A ticket with no due date stays unscheduled - set one explicitly if you want it to track the release.

**I don't see the cascade warning.** It only appears when at least one ticket in the version has a due date; with none, the date just saves.

**A ticket won't show up under its version on the overview page.** Confirm the ticket's **version** field (not just its milestone) is set to this version - milestones and versions are independent fields, and a ticket can belong to a milestone without being assigned to any version.


# Workflows and statuses (/user-guide/work/workflows-and-statuses)



Every ticket has a **status** - a word or short phrase describing where it stands: "To Do", "In Progress", "Waiting on Customer", "Deployed", whatever fits how your team talks about work. The set of statuses a project uses, in the order they're worked through, is often called its **workflow**. This page explains what a status is built from, how to design a project's own set of statuses, and what really controls whether a ticket can move from one to another.

## What a status is made of [#what-a-status-is-made-of]

A status has a **name** you choose freely (any text that fits your process), plus a few properties that make it behave correctly everywhere else in orboto:

* **Color** - shown on the ticket card and the Kanban column header.
* **Category** - one of five fixed buckets baked into orboto (see below). This is the part that isn't free-form, and it's what analytics, alerts, and progress tracking actually key off - not the name.
* **Terminal** - marks the status as a closing state. Moving a ticket into a terminal status stamps its `closed_at` timestamp.
* **Hidden on Kanban by default** - keeps a column off the board until someone opts in to see it.

### The five categories [#the-five-categories]

Every status - default or custom - belongs to exactly one category. Naming a status whatever you like ("QA", "Blocked", "Deployed") doesn't change the underlying bucket it reports into:

| Category        | Meaning                                                                     | What it drives                                                                                                                                            |
| --------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **To Do**       | Not yet started                                                             | Counts as open in burndowns                                                                                                                               |
| **In Progress** | Actively being worked on                                                    | -                                                                                                                                                         |
| **In Review**   | Done, pending review or QA                                                  | -                                                                                                                                                         |
| **Done**        | Completed and delivered                                                     | Counts toward progress %, sets `closed_at`, counts in velocity and cycle-time                                                                             |
| **Won't Fix**   | Closed without being delivered (scope removed, duplicate, no longer needed) | Also closes the ticket and sets `closed_at`, but is **excluded** from velocity and cycle-time so abandoned work never inflates "how fast are we shipping" |

Done and Won't Fix are both **terminal** categories (the ticket is closed either way), but only Done counts as *delivered*. That split exists so a project that closes a lot of tickets as out-of-scope doesn't look artificially fast or slow in analytics.

You can add as many custom statuses as you want - a "QA" status between In Progress and Done, a "Waiting on Customer" status for a support queue - as long as each one is assigned to one of these five categories.

## Where to configure statuses [#where-to-configure-statuses]

Open a project's **Settings → Statuses** tab. Changing anything here requires the `project:edit` permission.

{/* screenshot: the Statuses tab with the list of status rows and the add-status form */}

The tab's own explanation sums it up: it configures the workflow columns shown on the Kanban board, you can drag rows to reorder them, and every status must pick a category so analytics and alerts keep working.

### Default statuses on a new project [#default-statuses-on-a-new-project]

Every new project starts with five statuses:

| Name        | Category    | Terminal | Hidden on Kanban |
| ----------- | ----------- | -------- | ---------------- |
| To Do       | To Do       | No       | No               |
| In Progress | In Progress | No       | No               |
| In Review   | In Review   | No       | No               |
| Done        | Done        | Yes      | No               |
| Won't Fix   | Won't Fix   | Yes      | **Yes**          |

Won't Fix starts hidden on the board so a fresh project's Kanban isn't cluttered with a column most tickets never visit - toggle it visible any time (see below).

### Adding a status [#adding-a-status]

In the **Add status** form, enter a **name**, pick a **color**, and choose a **category**. New statuses are appended to the end of the list. Whether the status is terminal is set automatically from the category you pick (Done and Won't Fix are terminal by definition) - you can flip it manually afterward if you need a non-default combination.

Status names must be unique within a project; trying to add or rename to a name that's already taken is rejected.

### Editing a status [#editing-a-status]

Each row in the list is editable in place:

* **Color** - select the swatch to open a picker with eight presets plus a free-form hex picker.
* **Name** - select the text and type; saves when you click away.
* **Category** - change it from the dropdown at any time. If tickets are currently sitting in that status, they stay put - only their category-derived behavior (progress %, whether they count as closed) changes immediately.
* **Terminal** ("Sets closed\_at") - a checkbox you can toggle independently of category.
* **Hide/show on Kanban** - the eye icon toggles whether the column appears on the board by default.

### Reordering statuses [#reordering-statuses]

Drag a row by its grip handle. The order you set here is the left-to-right order of columns on the Kanban board.

### Deleting a status [#deleting-a-status]

Select the trash icon on a row. Two rules protect you from breaking a project:

* **A project always keeps at least one status.** Deleting the last remaining one is refused.
* **If any tickets are currently in that status, you must pick where they go.** The delete dialog shows a "Move tickets to" dropdown; every ticket in the deleted status is moved to the status you pick before the delete goes through. If the status is unused, no target is needed.

There's no undo - review the reassignment target carefully, especially on a status with many tickets in it.

{/* screenshot: the delete-status confirmation dialog with the "Move tickets to" dropdown */}

## How the Kanban board uses statuses [#how-the-kanban-board-uses-statuses]

The board shows **one column per status**, not per category - a project with eight custom statuses gets eight columns, laid out left to right in the order you set on the Statuses tab, and the board scrolls horizontally if they don't all fit. Category isn't a grouping mechanism on the board; it's the layer underneath that keeps analytics, burndowns, and alerts correct regardless of what you name things.

Any status flagged **Hidden on Kanban by default** doesn't appear as a column until someone turns on **Show hidden columns** above the board - handy for a Won't Fix-style status you rarely need to look at, without deleting it.

## What actually restricts a move [#what-actually-restricts-a-move]

By default, a ticket can move directly between any two statuses - there's no fixed sequence forcing it through "In Review" before "Done". Three real mechanisms can stop a move, and none of them are a per-status "allowed next statuses" list:

1. **Permission.** Moving a ticket between statuses (on the board, by drag, or from the ticket detail panel) requires its own permission, separate from general ticket editing. Without it, the move is refused.
2. **Open blockers.** A ticket can't be moved into a terminal status (Done, Won't Fix, or any custom status you flagged Terminal) while it still has open [dependencies](/user-guide/work/tickets#dependencies) blocking it. This check is not configurable and applies to everyone, including admins - a ticket with unresolved blockers is always a data-integrity problem, not a policy call. Close or resolve the blocking tickets first, or remove the dependency if it no longer applies.
3. **Approval gates.** A project can optionally require sign-off from specific people before a ticket may enter a chosen status - for example, before anything reaches "Released". This is the actual configurable transition restriction in orboto; see [Approval gates](/user-guide/work/approvals) for how to set one up and what happens when a gated move is attempted.

Any of the three shows up the same way: the move is rejected and the reason appears in a banner on the ticket (or, on the board, the card snaps back to its original column with the same message).

## Troubleshooting [#troubleshooting]

**I can't move a ticket to a status I know exists.** Check, in order: whether you hold the permission to change ticket status, whether the ticket has open blockers (visible under its Dependencies), and whether the target status has an approval gate awaiting sign-off (an **Approvals** panel appears on the ticket once a gated move is attempted).

**Adding or renaming a status fails with "already exists".** Status names must be unique per project - pick a different name, or edit the existing one instead of creating a duplicate.

**I deleted a status and now can't find where its tickets went.** Every ticket in a deleted status is moved to the reassignment target you picked in the delete dialog - check that status's column. There's no undo; ask a project admin whether a recent [backup](/admin/operations/backup) can help if the wrong target was picked.

**A status column isn't showing up on the Kanban board.** It's likely flagged **Hidden on Kanban by default** - toggle **Show hidden columns** above the board, or turn the flag off for that status in Settings → Statuses.

**Changing a status's category didn't move any tickets.** That's expected - tickets stay in the same named status; only the category-driven behavior (whether they count as open/closed, whether they show in velocity) changes.