Membership Plan

​

Background

• A tenant can provide shared Copilot models as the platform-wide default AI capability.
• An organization can configure its own Copilot models to meet model, cost, compliance, or private deployment needs.
• When users work inside an organization through AI Assistant, ClawXpert, Workspace Assistant, or other Copilot capabilities, the product must clearly decide which membership plan controls quota, rate limits, and usage reporting.

• An organization may have local models but no initialized organization membership plan, which can lead to scope mismatch errors.
• After an organization removes the tenant plan and intends to manage AI on its own, model lists and chat may still behave according to tenant fallback rules.
• Usage can be recorded under the wrong scope, making Usage Overview and Usage & Billing hard to explain.
• The product cannot clearly distinguish between tenant-provided AI and organization-managed AI cost ownership.

​

Product Goals

​

Goals

• Define the boundary between tenant membership plans and organization membership plans.
• Let organizations move smoothly between inheriting tenant AI capability and managing AI capability themselves.
• Automatically initialize organization membership when an organization enables local Copilot models, so users are not blocked by technical setup gaps.
• Make quota limits, rate limits, usage ledger records, and usage overview all belong to an explainable scope.
• Support unlimited plans for organization-owned models or internal cost scenarios where total point quota is not needed.

​

Non-goals

• Do not stack tenant and organization plans for the same usage event.
• Do not allow organization membership to limit tenant copilots, and do not allow tenant membership to directly limit organization copilots.
• Do not introduce plan selection interactions in the user chat flow.
• Do not introduce payment, subscription renewal, or invoicing in this design.

​

Core Concepts

​

Product Modes

​

1. Tenant-Provided Mode

• A new tenant should quickly provide shared AI capability to all organizations.
• The platform team manages model providers and Copilot models centrally.
• Organizations do not need custom models or independent AI cost ownership.

• Tenant admins configure membership plans in tenant scope.
• New users receive tenant-scope membership by default.
• If an organization has no active organization membership plan, organization users fall back to tenant membership.
• Users see only enabled tenant-scope Copilot models.
• Chat usage and ledger records are written to tenant membership.

​

2. Organization-Managed Mode

• Organization admins configure their own model providers or Copilot models.
• The organization wants to control model availability, quota, rate limits, and usage reporting.
• The organization wants to remove tenant-wide quota limits and use its own unlimited or fixed-quota plan.

• As soon as the current organization has an active organization membership plan, it enters organization-managed mode.
• Organization requests prefer organization membership and no longer fall back to tenant membership.
• Users see only enabled Copilot models in the current organization scope.
• Chat usage and ledger records are written to organization membership.
• If the organization has no enabled local copilots, the model list is empty even when an organization plan exists; it does not fall back to tenant models.

​

3. Local Model Self-Healing Mode

• Legacy data has local Copilot models in an organization, but no initialized organization membership plan.
• An organization admin removed the tenant membership plan during onboarding or settings and intends to use organization-managed AI.
• A user has already opened ClawXpert or AI Assistant inside the organization and started chatting.

• If the system finds enabled local Copilot models in organization scope and no organization membership plan, it performs one idempotent initialization.
• Initialization creates a default unlimited organization plan and assigns membership to all active organization members.
• After initialization, only organization Copilot models are returned.
• Future chat, limits, and ledger records belong to organization scope.

​

Scope Resolution Rules

​

Organization Requests

1. Look for active membership in the current organization scope.
2. If found, use organization membership.
3. If the organization has an active membership plan but the current user has no membership, reject usage and do not fall back to tenant.
4. If the organization has no active membership plan, look for tenant-scope membership.
5. If found, use tenant membership.
6. If neither exists, return no available models and block chat.

​

Tenant Requests

1. Look for active tenant-scope membership.
2. If found, use tenant membership.
3. If not found, return no available models and block chat.

​

Copilot Model Scope Validation

​

Plan Initialization Design

​

Default Organization Plan

{
  code: 'default-unlimited',
  name: 'Default Unlimited',
  includedPoints: null,
  tokensPerPoint: 1000,
  isDefault: true,
  status: 'active'
}

• The organization starts in unlimited mode, so organization-owned models are not accidentally blocked by total point quota.
• tokensPerPoint is still kept for usage ledger, reporting, and future cost conversion.
• Organization admins can later change unlimited to a fixed quota plan.

​

Initialization Strategy

• If an active default plan exists, use it.
• If active plans exist but none is default, mark the first active plan as default.
• If only an archived default-unlimited exists, reactivate it and make it default.
• If no usable plan exists, create a new default-unlimited plan.
• Create active UserMembership records for all active UserOrganization members in the current organization.
• Do not overwrite members who already have active membership.
• For unlimited assignment ledger records, use pointsDelta = 0.

​

Manual Initialization and Repair

• Initialize organization membership: used when the organization has no plan.
• Repair assignments: used when plans exist but member assignments are incomplete.

​

Usage and Limits

​

Point Limits

• includedPoints is the total point quota for the current cycle.
• Model usage converts tokens to points by token count and multiplier.
• If remaining points are less than or equal to zero, usage is rejected.

• includedPoints = null.
• Total point-limit checks are skipped.
• Points used for each call are still calculated.
• Usage ledger records are still written.
• Explicit rateLimits still apply.

​

Rate Limits

• Unlimited only means there is no total point cap.
• If the plan defines rate limits by hour, day, week, cycle, provider, or model, those limits still apply.
• This lets an organization use an unlimited plan while still throttling specific models or high-cost providers.

​

Ledger Ownership

• Tenant copilot usage writes to tenant membership ledger.
• Organization copilot usage writes to membership ledger in the same organization.
• If scopes do not match, no ledger is written and usage is rejected.

​

Page and User Experience

​

Settings Entry

• Tenant scope shows tenant membership plans.
• Organization scope shows organization membership plans.
• Access uses MEMBERSHIP_EDIT.
• Organization local admins can access the organization membership page when they have this permission.

​

Page Information Architecture

​

Empty States

• If the organization has no local copilots, explain that it is still inheriting tenant AI capability and can initialize organization membership when it wants to manage AI itself.
• If the organization already has local copilots, show an initialization call to action and explain that initialization creates a default unlimited plan and member memberships.

​

Plan Editing

• Creating plans.
• Editing plans.
• Setting the default plan.
• Archiving plans.
• Configuring includedPoints.
• Enabling unlimited mode by saving includedPoints = null.
• Configuring tokensPerPoint, model multipliers, and rate limits.

​

User Journeys

​

New Tenant Fast Start

1. Tenant admin configures tenant Copilot models.
2. Tenant admin configures a tenant default membership plan.
3. New users receive tenant membership.
4. Users enter organizations. If the organization has no organization plan, they use tenant models.
5. Usage is recorded under tenant membership.

​

Organization Switches to Managed Mode

1. Organization admin enters organization scope.
2. Admin configures organization-owned Copilot models.
3. Admin opens Settings / Membership.
4. Admin clicks Initialize organization membership.
5. The system creates a default unlimited plan and assigns membership to active members.
6. Organization users see only organization Copilot models.
7. Usage is recorded under organization membership.

​

Legacy Data Self-Healing

1. An organization already has enabled local Copilot models but no organization plan.
2. A user opens ClawXpert or requests the model list.
3. The system detects local models and performs idempotent initialization.
4. The model list returns organization models.
5. Chat succeeds and the ledger is written to organization membership.

​

New Member Joins an Organization-Managed Organization

1. A new user joins the organization.
2. User bootstrap runs.
3. If the organization already has an active membership plan, the user receives active membership.
4. If the organization has no active plan, no membership plan is created.

​

Permission Design

​

Boundaries and Exceptions

​

Organization Has a Plan but No Local Copilots

​

Organization Has Local Copilots but No Plan

​

User Has No Assignment

​

Tenant Membership and Organization Membership Both Exist

​

Plan Deletion or Archiving

​

Future Improvements

• Let organization admins choose fixed quota or unlimited mode during initialization.
• Support cloning a tenant plan into an organization plan.
• Add clearer membership health checks, such as missing plan, missing default, missing assignment, or no local models.
• Show estimated cost by provider and model, not only points.
• Connect plan lifecycle to real subscription and payment systems.