AI governance
Route: /org/ai-governance · Permission: AI governance — view (manage to set role caps)
Module: AI Studio · Entry points: Settings → AI · global search "ai governance"
What this is. What your organization's AI cost, who spent it, and every change it made. What it is for. Answering "what is the AI actually doing in here?" with evidence rather than assurance. The problem it solves. AI features are easy to switch on and hard to account for. This is the accounting.
1. What the page shows
| Section | Answers |
|---|---|
| Totals | Credits used and left, runs, how many fell back to a non-AI answer, estimated cost |
| Where the credits went | Broken down by capability, by person, or by day |
| Monthly ceiling per role | What each role may spend, and what it has spent |
| What AI changed | Every change an AI applied, with before and after, and whose authority it was |
| How AI is used here | A plain statement for the people who must answer that to a regulator or a customer |
2. The change ledger
Every time an AI capability changes real data — the Orbit Agent applying an approved action, someone clicking Apply on a risk intervention, an assistant write tool — a line is written recording:
- what changed, with the values before and after
- who it was applied as (usually the Orbit Agent system user)
- on whose authority — the person who approved it
- which capability proposed it
The database rejects an UPDATE or DELETE on the ledger outright. An audit trail that can be
quietly corrected is not an audit trail. A wrong entry is answered by appending, never by rewriting.
The Orbit Agent is a system user with no password and no organization. It cannot sign in. It exists only so that a change made on someone's approval has an honest author.
3. Monthly credit ceiling per role
Set a monthly credit ceiling on any role. When the people holding that role have spent it:
- their AI calls fall back to the non-AI answer rather than failing — nobody is left staring at an error they cannot act on
- the ceiling resets on the first of the month
- scheduled jobs are never capped: they belong to no role, and a nightly risk run must not stop because one team ran out of budget
0 means no cap. Needs AI governance — manage.
4. CSV export
CSV downloads the raw usage log for the chosen dates: timestamp, capability, person, status, whether it fell back, credits and estimated cost — one row per call, up to 50,000.
5. Who can see this
Seeded on the admin role tier only, deliberately: the page shows what every named person spent and everything AI changed.
Before this page existed, the organization-wide AI usage logs — which contain every AI call's inputs
and outputs — were readable by any signed-in user. GET /org/ai-utilities/usage-logs and
/usage-stats now require AI governance — view. If internal tooling read those endpoints, grant it
the permission.
GET /org/ai-utilities/settings deliberately stays open to any signed-in user: it is a feature gate
every AI surface reads, not usage data.
6. The Orbit Agent
Switched on per project in Project settings → Risk. When enabled, it reviews that project's risk radar each morning and proposes a few actions.
| Control | Default | What it does |
|---|---|---|
| Let the agent propose | Off | Nothing happens until this is on |
| What it may propose | Reassign, extend | The two reversible verbs. Descope, unblock and escalate post a comment for the owner and must be added deliberately. Splitting a task is never proposed — that needs a person |
| Most proposals per day | 5 | A flood of proposals is how an assistant becomes noise people stop reading |
| Proposals lapse after | 3 days | A proposal nobody looked at is not an instruction |
| Approver role | none | When set, only holders of that role may approve — on top of Manage risk radar |
Approving is what applies a change. It then goes through the same route, the same permission checks and the same ledger as a manual edit. The auto-apply settings you may see in the database are seeded and deliberately not connected to any code.
Each proposal can be previewed before approval — the same what-if that shows you how the risk picture moves, without changing anything.
7. Administrator setup
| Step | Where |
|---|---|
Apply migrations 001175, 001176, 001177 | Release-0.1.6/ |
Grant org.ai.governance.menu/.view/.manage | Settings → Roles |
| Switch on the agent per project | Project settings → Risk |
| Verify the ledger is append-only | Run the UPDATE in the manual-actions doc; it must fail |
8. Downstream
- Risk radar — the agent's proposals panel and its settings
- Project settings → Risk — the agent controls
- Every apply path across Orbit Ops AI writes to the ledger this page reads
9. Don't confuse this with…
| This | That |
|---|---|
| AI governance — organization-wide spend and changes | AI Utilities — which capabilities exist and their per-utility limits |
| The change ledger — what AI changed to your data | The usage log — every AI call, including ones that changed nothing |
| Role credit cap — a monthly ceiling per role | Per-utility monthly limit — a ceiling per capability, set in AI Utilities |
| Orbit Agent — proposes on a schedule | Risk advisor — answers when you ask |
10. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The page 403s | Missing org.ai.governance.view | Grant it in Settings → Roles |
| The ledger is empty | Nothing has been applied through an AI path yet | Apply a risk intervention, or approve an agent proposal |
| Someone's AI stopped working | Their role hit its monthly ceiling | Raise the cap, or wait for the month to roll |
| No agent proposals | The agent is off for that project, or nothing was worth proposing | Check Project settings → Risk; the nightly job must be enabled |
| "Your role is not allowed to approve" | The project sets an approver role | Ask a holder of that role, or clear the setting |