AI limits - KayanOS Documentation

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

Confirm you are the organization owner and that the requested change has budget, security, and service-owner approval.
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.
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.
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.
Define the human review outcome: who checks the proposal, where corrections are recorded, and who decides whether it is saved or published.
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.

Read the organization-level used, remaining, and status information. If usage is near a limit, identify the feature and member before increasing the total.
Set the organization limit to the approved policy value. Record the approving owner and effective date.
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.
Set a member allocation that is proportionate to a specific approved purpose. The member limit should not exceed the organization’s governance decision.
Use bulk editing only for a reviewed cohort with the same policy reason. Recheck the selected members before saving.
Inspect feature usage columns or summaries to understand what consumed usage. A high total without feature context is not enough evidence for an increase.
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:

Check the organization and member status and remaining values.
Check which feature used the allocation and whether the use matches the approved purpose.
Confirm the member still needs the capability and has the underlying role/permission.
Decide to wait for the organization’s approved renewal, reduce unnecessary use, or request a documented adjustment.
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

Review AI-assisted application proposals in AI builder and import.
Protect configuration through Roles and scopes.
Design request fields before reviewing a proposal in Plan an app before building.
Diagnose unavailable controls in Permissions and availability.

KayanOS AI limit settings for the Directorate of Citizen Services.

​Goal

​Access and allocation model

​Before changing a limit

​Set organization and member limits

​Controlled Directorate scenario

​When a limit is exhausted

​Safe validation

​Troubleshooting

​Related guides