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

# Team Template Schemas

> Normative JSON Schemas for team-scope alignment + protection templates.

This page documents the **normative** JSON Schemas for team-scope alignment + protection templates.

Team templates share their on-the-wire shape with **agent cards** at the same kind: an alignment template is a partial alignment-card body; a protection template is a partial protection-card body. Server-side validation runs the same agent-card validators with a small allow-list of "may legitimately be omitted at template scope" fields (see [Allow-list](#template-scope-allow-list) below).

## Endpoints

| Endpoint | Method | Body shape |
| - | - | - |
| `/v1/alignment/team/{team_id}` | GET | response: `{ team_id, org_id, name, template, enabled }` (add `?include=sources` for the envelope below) |
| `/v1/alignment/team/{team_id}` | PUT | request: alignment template body (see [Alignment template schema](#alignment-template-schema)) |
| `/v1/alignment/team/{team_id}` | DELETE | response: `{ team_id, org_id, template: null, enabled: false, deleted: true, agents_flagged_for_recompose }` |
| `/v1/alignment/team/{team_id}/preview-compose` | POST | request: alignment template body; response: `{ ok, composed, conflicts }` |
| `/v1/protection/team/{team_id}` | GET | response: same shape as alignment, but `template` is a partial Protection card |
| `/v1/protection/team/{team_id}` | PUT/DELETE/preview-compose | mirrors alignment |

Body content types accepted on PUT and preview-compose: `application/json`, `text/yaml`, `application/yaml`. JSON envelope shape `{ template, enabled? }` or `{ template_yaml, enabled? }` is also accepted; bare-template JSON works too. Idempotency-Key header required on PUT/DELETE.

Body size limits: **128 KiB** alignment / **64 KiB** protection (mirrors org-scope template limits).

## Alignment template schema

A team-scope alignment template is a **partial** [Alignment Card](/specifications/alignment-card-schema). The composer reads the same field paths the agent card reads, but a template legitimately omits fields that are author-specific (`agent_id`, `card_version`, etc. — see allow-list).

Fields that are **typically authored** at team scope:

| Field | Purpose | Composition rule |
| - | - | - |
| `autonomy_mode` | Override platform/org's autonomy mode for this team's agents (strictest wins) | Enum precedence (`enforce > nudge > observe > off`) |
| `integrity_mode` | Override platform/org's integrity mode | Enum precedence |
| `values.declared` | Add team-specific values to the agent's declared list | Union across layers |
| `values.conflicts_with` | Add team-specific value conflicts | Union |
| `conscience.mode` | Force conscience replace mode at team scope | Strictest (any layer setting `replace` wins) |
| `conscience.values` | Add team commitments / boundaries | Union (or sole source in `replace` mode) |
| `autonomy.bounded_actions` | Permit additional bounded actions for the team | Union |
| `autonomy.forbidden_actions` | Forbid additional actions for the team | Union (deny-overrides) |
| `autonomy.escalation_triggers` | Add team-specific escalation conditions | Union, deduplicated by `condition` (first occurrence wins) |
| `autonomy.max_autonomous_value` | Tighten the team's autonomous-decision floor | Min across layers |
| `capabilities.<name>` | Per-capability tools / allowed\_domains / severity\_on\_unmapped | Per-name merge (union tools, union domains, strictest severity) |
| `enforcement.forbidden_tools` | Add team-specific forbidden tool patterns | Union with dedup by pattern |
| `enforcement.allow_unmapped_tools` | Tighten unmapped-tool policy | False beats true (strictest) |
| `enforcement.default_unmapped_severity` | Tighten unmapped-tool severity | Strictest |
| `enforcement.grace_period_hours` | Tighten the team's grace period | Min |
| `audit.retention_days` | Strengthen audit retention for the team | **Max** (the only audit field a team may strengthen) |

Other `audit.*` fields (`trace_format`, `queryable`, `query_endpoint`, `tamper_evidence`) are **platform-scoped**: a team may *propose* values, but the composer ignores them in favor of the platform values. Teams cannot widen the platform's audit-storage commitments.

## Protection template schema

A team-scope protection template is a **partial** [Protection Card](/specifications/protection-card-schema). Fields:

| Field | Composition rule |
| - | - |
| `mode` | Strictest wins: `enforce > nudge > observe > off` |
| `thresholds.{warn,quarantine,block}` | Min across layers (lower = stricter) |
| `screen_surfaces.{incoming,outgoing,tool_calls,tool_responses}` | OR per field (true = scan more = stricter) |
| `trusted_sources.{domains,agent_ids,ip_ranges}` | Org + every team + agent contribute additively (union); intersected with platform ceiling |

## Template-scope allow-list

The server-side validator reuses the agent-card validator with one accommodation: certain fields that are **required on a full agent card** are legitimately absent on a template. The validator filters validation errors keyed to these field paths + the `required`-class rules:

```text theme={null}
card_version, agent_id,
autonomy_mode, integrity_mode,
principal, principal.type, principal.relationship, principal.identifier,
values.declared,
autonomy.bounded_actions,
audit, audit.retention_days, audit.queryable, audit.trace_format,
mode (protection)
```

Rules ignored on these field paths: `required`, `required_enum`, `required_when_typed`, `non_empty`. Other validation rules (enum membership, BOUNDARY rejection, disjoint-action checks, regex syntax for `forbidden_tools.pattern`, etc.) still apply.

## Composition output

`GET /v1/alignment/team/{team_id}?include=sources` returns the team-scope **sources envelope** — the three contributing layers (**platform / org / team**) plus the **composed** result:

```json theme={null}
{
  "platform": { "card_json": { ... }, "available": true },
  "org":      { "card_json": { ... }, "available": true,  "org_id": "org-..." },
  "team":     { "card_json": { ... }, "available": true,  "team_id": "...", "team_name": "platform" },
  "composed": { "card_json": { ... }, "available": true },
  "composed_stale": false,
  "my_role": "owner"
}
```

`available: false` for a layer that has no enabled contribution; `my_role` is the caller's effective role on the team. The dashboard team-template editor renders the four rows (platform, org, team, composed). `?include=sources` is an all-scope feature — each scope (agent / org / team / platform) returns a scope-appropriate envelope. The **agent**-scope envelope adds an `agent` layer and a `teams[]` array (an agent can belong to several teams); a solo agent with zero teams therefore sees `teams: []`.

## Audit + recompose

Successful PUT or DELETE emits a `governance_audit_log` row:

| Action | Target type | `before_json` | `after_json` |
| - | - | - | - |
| `team_alignment_template.put` | `team` | prior template + enabled flag | new template + enabled flag |
| `team_alignment_template.delete` | `team` | prior template + enabled flag | `null` |
| `team_protection_template.put` | `team` | prior | new |
| `team_protection_template.delete` | `team` | prior | `null` |

`metadata` carries `org_id`, `team_name`, and `agents_flagged_for_recompose` (the count of canonical-card rows scoped to **this team's** active agents that were flipped to `needs_recompose=true`).

The recompose fan-out is scoped to the team's agents only — never a blanket org flip. Background recompose then re-runs the composer for each flagged agent against the new template.

## See also

* [Team Scope (concept)](/concepts/team-scope) — model overview
* [Alignment Card Schema](/specifications/alignment-card-schema) — full agent-card schema (template is a partial form)
* [Protection Card Schema](/specifications/protection-card-schema)
* [Card Composition](/concepts/card-composition) — the layered cascade


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.