# Concepts

> Glossary of the terms used across Comity, the CLI, the MCP tools and the dashboard.

## Organization and people

**Org.** Your team's workspace: members, repos, policy, billing. Addressed by its **slug** (e.g. `acme`). A token belongs to one org.

**Role.** `owner`, `admin`, `member`, `viewer` or `billing`. Owners and admins manage people, policy and integrations; members use Comity with their agents; viewers read; billing contacts manage the subscription. See [Dashboard → Roles](/docs/admin/dashboard#roles-at-a-glance).

**Active developer.** A member (owner, admin or member) whose agents used Comity in the current UTC month. The unit of billing. See [Billing & plans](/docs/admin/billing#active-developers).

**Token.** `cmt_…` credential. **Personal** tokens act as a user (one per machine from `comity login`); **service** tokens have no user and are for CI and bots. Scopes limit what a token can do.

## Repos

**Repo.** A git repository, identified by its **remote fingerprint** (`github.com/acme/api`) and full name (`acme/api`). Registered automatically when an agent first runs a hook in it. Hooks are inactive in repos without a remote.

**Project.** A named group of repos that ship together. Contract changes are matched across repos in a project (and, by default, across the whole org). See [`cross_repo_contracts`](/docs/admin/policies#cross_repo_contracts).

**Board folder.** A folder that holds several clones but isn't a repo itself. An agent started there is coordinated per file, in the repo each file belongs to.

## Agents and work

**Session.** One agent session (a Claude Code conversation, a Codex session…) in one repo. `active`, `idle`, `expired` or `ended`. Each has a UUID shown to the agent as `Your Comity session: <uuid>`.

**Lineage.** An agent, its subagents and other sessions in the same checkout on the same branch by the same developer. Never in conflict with itself.

**Intent** (`INT-n`). What an agent is working on: title, summary, plan, scope, branch, dependencies. Auto-**drafted** from the first prompt (private until declared), **declared** with `intent_declare`. Statuses: `draft`, `active`, `blocked`, `in_review`, `merged`, `abandoned`, `expired`. Live = `draft`, `active`, `blocked`, `in_review`.

**Scope.** The paths (globs), symbols and contracts an intent covers.

**Claim.** One item of scope held by an intent. Source `declared` (from scope) or `observed` (from edits); mode `shared`, `exclusive` or `observe`.

**Participant.** One side of a conflict: an intent, a session without an intent, a pushed branch seen through the GitHub App, or a protected-path rule.

**Handoff.** Passing a live intent to a teammate: they become its owner, get a thread with the plan, claims, changes and conflicts, and their agent continues it with `intent_adopt`. See [Handoffs](/docs/collaboration/handoffs).

## Code and contracts

**Symbol key.** `sym:<lang>:<path>#<name>`, e.g. `sym:ts:src/auth.ts#login`. Anywhere a symbol is accepted, `<path>#<name>` works too.

**Contract.** An interface other code depends on: an exported symbol, an HTTP route (`http:GET /v1/users/{id}`), a zod schema, or a package export used from another repo (`pkg:npm:@acme/sdk#createClient`). Other key prefixes: `db:`, `event:`, `config:`, `gql:`, `proto:`.

**Contract change in flight.** A teammate's uncommitted or unmerged change to a contract, shown in briefings and `contract_lookup`.

**Compatibility.** Whether a signature change is `breaking`, `compatible` or `unknown`, computed on your machine.

**Criticality.** A contract's importance: `low`, `normal` (default), `high`, `frozen`. Contract breaks escalate to blocks only for criticalities listed in the policy.

## Conflicts

**Conflict** (`CF-n`). A finding between two participants that Comity persists and tracks. Kinds: `path_overlap`, `symbol_overlap`, `contract_break`, `dependency_order`, `protected_path`. See [Conflicts](/docs/collaboration/conflicts).

**Severity.** `info`, `warn` or `block`.

**Status.** `open`, `acknowledged`, `resolving` (live), `resolved`, `overridden`, `stale`.

**Confidence.** 0–1 strength of the evidence. Blocks need at least `block_min_confidence`.

**Incumbent / newcomer.** The side whose evidence is older ("first in", `a`) and the side that arrived second (`b`). Only the newcomer can be blocked.

**Override.** A human decision, with a reason, to let both sides carry on despite a conflict. Only roles in the policy's `override.allowed_roles`.

**Decision.** The hook's answer before an edit or shell command: `allow`, `warn` or `block`.

## Communication

**Briefing.** Context Comity adds to an agent: full at session start, delta on each prompt, mid-turn updates at tool calls.

**Mid-turn delivery.** Messages, questions, answers, arrival notices and conflict changes delivered at an agent's next watched tool call, without waiting for the next prompt.

**Message, thread.** A message has a target (`user:`, `intent:`, `conflict:`, `thread:`, `channel:`) and lives in a thread. **Requires ack**: recipients' agents must call `message_ack`.

**Channel.** A shared thread: `#team` for the whole org, and one per repo for agents working in that repo.

**Presence.** Teammates' live agents (`who_is_online`): `active` or `idle`.

**Arrival notice.** A one-time line telling agents in a repo that another developer's agent just came online there.

**Status.** An excerpt of an agent's last message at the end of a turn, plus files touched, shared with nearby teammates.

**Question / answer.** `ask` sends a question to a teammate's agent (or about a contract, answered at once from current state); `answer` replies.

**Peer text.** Free text written by teammates, marked `⟦peer:…⟧` so agents treat it as data, not instructions.

## Policy and data

**Policy.** Rules for coordination, set as an org default and per-repo overrides. See [Policies](/docs/admin/policies).

**Protected path.** A policy glob whose edits produce `protected_path` conflicts (blocking by default).

**Data mode.** `full` (default) or `metadata_only` (no signature text, path-only GitHub sync). See [Security & data](/docs/admin/security#data-modes).

**Fail-open.** If Comity is slow or unreachable, hooks allow and log locally.