---
name: multi-tenancy-and-orgs
description: Model org/team-aware tibi projects. Covers the org-team-user hierarchy, visibility vs working rights, permission resolution, project assignment, audit visibility, and how later agents should make an explicit single-tenant vs org/team decision.
---

# multi-tenancy-and-orgs

## When to use this skill

Use this skill when:

- a project might need org/team-aware isolation or working rights
- multiple organizations or departments share one tibi installation
- project visibility and editing rights must be separated cleanly
- LLM budget ownership or audit visibility must follow org boundaries

## Goal

Give later agents a concrete implementation workflow for enterprise-aware projects and a clear off-ramp for single-tenant projects.

The most important decision is not how to model orgs. It is whether the project should use org/team features at all.

## Source of truth

Use these sources when implementing or reviewing org/team-aware projects:

- `tibi-server/docs/18-orgs-teams.md`
- `tibi-server/docs/05-authentication.md`
- `tibi-server/docs/17-field-level-permissions.md`
- `.agents/skills/permissions-and-editor-workflows/SKILL.md`
- `.agents/skills/search-and-embeddings/SKILL.md` when LLM budget or shared AI/search budgets matter

## First decision: single-tenant or org/team-aware

Make this decision explicitly.

### Single-tenant projects

Recommended shape:

- do not model org/team support by default
- document that visibility and permissions are handled without enterprise isolation
- keep the project simpler unless there is a real multi-tenant requirement

### Org/team-aware projects

Use this branch only when you actually need:

- org-scoped project visibility
- team-based working rights
- cross-user governance inside shared organizations
- org-level budget ownership or audit visibility constraints

## Core model

The upstream hierarchy is:

- org = visibility boundary
- team = working-rights unit
- user = member of orgs and teams

Key fields include:

- `project.orgId`
- `project.teams[]`
- `user.orgs[]`
- `user.teams[]`
- `user.primaryOrgId`

Do not flatten these concepts into a generic “role” discussion. Org visibility and team working rights are different concerns.

## Visibility vs working rights

Important rule:

- org membership controls which projects a user can see
- team assignment controls which permission sets a user gets inside those visible projects

This is the main conceptual boundary later agents must keep intact.

If a user can see a project but cannot edit it, that can be correct. Visibility is not the same as edit access.

## Permission resolution

Team permissions map onto collection permission keys.

Example idea:

- team carries `permissions: ["editor"]`
- collection defines an `editor` permission set
- assigned team members inherit that working-rights set on the project

Also important:

- multiple team permissions merge as a union
- admin tokens and system admins still sit above team-based resolution
- token/public/user/team/custom permission order matters

## Project assignment rules

For org/team-aware projects, later agents must design all of these deliberately:

- which org owns the project
- which teams are assigned to the project
- who is allowed to manage those assignments
- how custom collection permission keys map to teams

Half-modeled org/team setups create the worst of both worlds: extra complexity without trustworthy isolation.

## Audit and LLM implications

Enterprise modeling affects more than CRUD visibility.

Relevant side effects:

- audit visibility follows the team → project → collection access chain
- non-admin users do not see system audit entries
- LLM/org budget logic uses `user.primaryOrgId`

That means enterprise design can affect audit reviews and AI cost ownership even if the public website itself looks simple.

## Anti-patterns

- enabling org/team concepts “just in case”
- using teams as visibility boundaries instead of orgs
- mixing custom collection permissions and team permissions without naming discipline
- forgetting that users can belong to multiple teams
- introducing org-aware billing or audit expectations without modeling `primaryOrgId`

## Verification checklist

After org/team-related changes, verify all of these:

1. the project explicitly states single-tenant or org/team-aware
2. org ownership and team assignment are defined for enterprise projects
3. collection permission keys map cleanly to team permissions
4. representative visibility and edit-rights scenarios behave as designed
5. audit and LLM budget implications are understood when those features are in scope

## What an LLM should inspect first

When asked whether a project needs enterprise features, inspect in this order:

1. the project's actual tenancy requirement
2. `tibi-server/docs/18-orgs-teams.md`
3. current permission model in collection configs
4. whether audit visibility or LLM budgets depend on org ownership
5. whether the simpler single-tenant branch is the right answer

This prevents unnecessary enterprise complexity in projects that only need normal editorial permissions.