tibi-svelte-starter/.agents/skills/multi-tenancy-and-orgs/SKILL.md

name, description

name	description
multi-tenancy-and-orgs	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.