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

# AI limits

> Allocate and review organization and member AI usage limits by feature, with controlled tests and no assumption that generated output is approved or published.

AI limits are organization-governance controls. They help an organization owner allocate a bounded amount of AI-assisted work across members and features, review usage, and respond when a member or organization reaches a limit. They do not grant Builder access, publish an application, make a proposal correct, or authorize a member to access underlying records.

For the Directorate of Citizen Services, use a small controlled allocation when a builder prepares a proposed request application. The proposal must still be reviewed for fields, scopes, forms, Arabic labels, and service policy before any administrator saves or publishes it.

## Goal

Set and review AI usage limits in a transparent hierarchy, distinguish organization capacity from member allocation, and test a bounded use case without sending sensitive citizen data or accepting generated output automatically.

## Access and allocation model

The AI limits settings surface is controlled for the organization owner. It shows organization-level limits and active-member rows with usage, remaining capacity, and status. It also supports feature-oriented usage review, status/search filtering, and bulk changes. The combined **Recorded usage** metric is summed from recorded feature events for active members; it is not recalculated as current member limits minus current remaining balances. General assistant and SOP assistant turns are attributed to separate feature labels when the recorded turn actually uses an SOP capability.

| Layer                 | What it answers                                                             | Administrative responsibility                                                |
| --------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Organization limit    | How much approved AI usage the organization may consume                     | Set the total only after policy/budget approval                              |
| Member limit          | Which member receives a bounded share                                       | Give the smallest allocation needed for their work and review date           |
| Feature usage         | Which enabled use case consumed capacity                                    | Investigate unusual use rather than assuming all features have the same risk |
| Remaining/used/status | Whether the current allocation is usable, close to exhaustion, or exhausted | Explain the work impact and decide whether adjustment is justified           |

The interface may have implementation defaults, but public documentation should not treat an implementation default as a contractual quota. Your organization should publish its own approved limits, eligibility, review cadence, and escalation path.

## Before changing a limit

1. Confirm you are the organization owner and that the requested change has budget, security, and service-owner approval.
2. Identify the member, feature, business purpose, expected duration, and maximum approved use. Avoid an organization-wide increase to solve one person’s short-term need.
3. Confirm the member already has the normal permission needed for the underlying work. AI capacity cannot create/update an entity or field for someone who lacks Builder access.
4. Decide what data may be included in the prompt or attachment. Do not submit citizen identifiers, confidential documents, secrets, private keys, or unapproved case evidence merely because usage is available.
5. Define the human review outcome: who checks the proposal, where corrections are recorded, and who decides whether it is saved or published.
6. Set a review/expiry date for a temporary member allocation and a named owner for unexpected consumption.

## Set organization and member limits

Open **Administration → AI limits**. Review the organization summary before editing individuals.

1. Read the organization-level used, remaining, and status information. If usage is near a limit, identify the feature and member before increasing the total.
2. Set the organization limit to the approved policy value. Record the approving owner and effective date.
3. Search or filter the member table to find the intended member. Use status filters to identify members with no allocation, active capacity, or exhausted capacity.
4. Set a member allocation that is proportionate to a specific approved purpose. The member limit should not exceed the organization’s governance decision.
5. Use bulk editing only for a reviewed cohort with the same policy reason. Recheck the selected members before saving.
6. Inspect feature usage columns or summaries to understand what consumed usage. A high total without feature context is not enough evidence for an increase.
7. Save, then reopen the row/summary to confirm the new used, remaining, and status presentation.

Limits govern capacity; they do not decide whether the proposed content is safe. A member with available capacity must still review inputs, correct output, and use normal permission/publishing controls.

Changing a limit preserves all usage already consumed, including an internal over-limit balance. The interface never shows negative available credit—it shows zero and **Exhausted**—but raising an exhausted limit by less than the accumulated overage can therefore leave it exhausted. This prevents a sequence of limit reductions and increases from manufacturing new credit. Approve the policy limit itself; do not keep increasing it until the status happens to change.

## Controlled Directorate scenario

The Directorate allows one Builder to prepare a draft proposal for a **Citizen Service Request** application. The organization owner sets a small approved member allocation for a limited period and records the purpose: prepare a structure for review, not publish a live service.

The Builder uses synthetic service fields only—request category, service centre, status, inspection relation, and an estimated fee concept. The Builder reviews every proposed field, rejects a field that would collect unnecessary personal data, and saves nothing until the service owner and access administrator approve the design. The owner then reviews the feature usage summary and confirms that the allocation is still justified.

Expected result: usage is visible and bounded; no citizen data has been sent; no application, role, form, or public portal appears automatically; and the proposal remains subject to normal review.

## When a limit is exhausted

An exhausted or unavailable status is a governance signal. Do not instruct members to create another account, use someone else’s allocation, or retry a request indefinitely.

Use this decision path:

1. Check the organization and member status and remaining values.
2. Check which feature used the allocation and whether the use matches the approved purpose.
3. Confirm the member still needs the capability and has the underlying role/permission.
4. Decide to wait for the organization’s approved renewal, reduce unnecessary use, or request a documented adjustment.
5. If an adjustment is approved, make the smallest policy-justified change, save it, and verify it in the member row. If remaining stays at zero, compare the approved new limit with the recorded usage/overage instead of repeatedly increasing it.

An AI response is assistance, not an official record. Keep the service decision, data model, and publication approval in their configured human workflows.

## Safe validation

| Test                 | Expected result                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| Organization summary | Shows used, remaining, and a status consistent with the approved allocation                             |
| Member allocation    | The selected controlled member receives only the intended bounded capacity                              |
| Feature review       | Usage can be inspected by enabled feature rather than treated as one unexplained total                  |
| Exhaustion scenario  | The status explains unavailable/exhausted capacity; the team follows escalation instead of bypassing it |
| Permission boundary  | A member without Builder/resource permission cannot use capacity to change protected configuration      |
| Output review        | A synthetic proposal is reviewed and corrected before any save/publish action                           |

## Troubleshooting

| Symptom                                            | Check first                                                                                 | Safe response                                                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI limits page is unavailable                      | Organization-owner access and current organization context                                  | Ask the organization owner to review the request; do not share an owner account                                                                                       |
| A member has no usable capacity                    | Member allocation, organization remaining amount, status, and feature eligibility           | Follow the approved allocation process; do not borrow another member’s allocation                                                                                     |
| Remaining stays at zero after an approved increase | Prior usage exceeded the old limit by more than the increase                                | Review recorded feature usage and the approved ceiling; a smaller increase does not erase overage, so do not keep raising the limit without a new governance decision |
| Usage appears higher than expected                 | Feature usage summary, time period, selected member, and repeated attempts                  | Investigate the evidence before changing any limit                                                                                                                    |
| General assistant and SOP assistant totals differ  | Whether recorded turns invoked an `sop.*` capability and whether the member is still active | Use the separate feature categories for attribution; do not infer record access, output quality, or approval from the usage label                                     |
| A bulk change affected the wrong people            | Selected rows, filters, and saved values                                                    | Restore the approved allocations and record the correction                                                                                                            |
| Generated proposal is inaccurate                   | Input clarity, available context, and human review                                          | Edit/reject the proposal; do not publish it because it was generated                                                                                                  |
| A member still cannot save configuration           | Underlying Builder/entity/field permission and scope                                        | Resolve normal permissions separately from AI capacity                                                                                                                |

## Related guides

* Review AI-assisted application proposals in [AI builder and import](/build/ai-builder-and-import).
* Protect configuration through [Roles and scopes](/admin/roles-and-scopes).
* Design request fields before reviewing a proposal in [Plan an app before building](/build/plan-an-app).
* Diagnose unavailable controls in [Permissions and availability](/reference/permissions-and-availability).

![KayanOS AI limit settings for the Directorate of Citizen Services.](https://kayanos.app/docs-images/en/admin/ai-limits.png)