# Teams & workspaces

## What exists today (product)

In the builder, open **Go live → Share & invite**:

- **Invite by email** — Send access / collaboration flows (see in-app copy).
- **Team workspaces** (details panel) — Create a workspace, list workspaces, and **assign this agent to a workspace** so org-bound features stay scoped.

Use this for **small teams** sharing agents before full seat-based billing is productized.

## Workspace governance (API + UI)

**Owner/admin** can store optional workspace **`settings`** (Postgres `organizations.settings` JSON):

- **`defaults.runLogRetentionDays`** — `30` | `90` | `180` | `365` (recommended log retention for members; each member’s **Account → Usage** preference still controls their own purge until they align).
- **`defaults.usageAlertThreshold`** — `0`–`100` (recommended % of plan cap for usage-alert email nudges).
- **`spendGuard.monthlyUsdCap`** — advisory USD cap for **combined** estimated token spend (30-day heuristic, same formula as Account → Usage).

**API**

- `GET /api/organizations/:id` — includes `role` and `settings`.
- `PATCH /api/organizations/:id` — body `{ "settings": { "defaults": { … }, "spendGuard": { … } } }` (validated merge).
- `GET /api/organizations/:id/usage-rollup` — owner/admin only; per-member `runsLast30Days`, `estimatedCostUsd30d`, emails, plus totals and **`pctOfCap`** when a monthly cap is set.

In-app: **Go live → Team workspaces** for create/invite/assign; **Workspace defaults & spend guard** is a separate disclosure below it (loads automatically when opened if a workspace is selected on this agent).

## Roadmap (pricing & scale)

Longer term (see **`docs/PRODUCT-ROADMAP.md`**):

- **Seat-based pricing** aligned with workspace growth.
- Clearer **roles** (admin vs member), **shared usage** visibility, and **billing owner** per workspace.

## Related

- **Founder path** — **[FOUNDER-PATH.md](./FOUNDER-PATH.md)**  
- **Analytics** — workspace-scoped metrics may layer on **`FOUNDER-ANALYTICS.md`** events over time.