# AI Spend Caps

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/ai-spend-caps` |
| Package slug | `ai-spend-caps` |
| Product group | Capell AI |
| Tier | free |
| Bundle | `ai` |
| Runtime contexts | `admin` |
| Capell version | `^1.0` |
| Catalogue role | extension |
| Release channel | Labs |
| Docs source | `packages/ai-spend-caps/docs` |
| Manifest | `capell.json` |

<!-- prettier-ignore-start -->

Someone on your team uses an AI feature all afternoon, and nobody sees what it cost until the figures come in. Here you set one monthly budget that covers every site and a daily limit for each person. Once either one is used up, Capell stops further AI requests. AI Spend Caps works on top of AI Orchestrator, which runs the requests.

When spending reaches the share of the budget you choose, the person you name gets one email for that month. An editor who hits a limit sees a short message saying which one it was, so they know whether to wait or ask an administrator to raise it.

An AI usage page in the admin shows where the money went, split by AI task, by person and by site. The figures are estimates, worked out from how much text each request used and a price list your developer keeps up to date. They won't match an invoice to the penny. If you'd rather watch than block, turn the hard stop off and keep the warning and the usage page.

- **Price and availability:** Check current availability and price on the [Capell Marketplace listing](https://capell.app/extensions/ai-spend-caps).
- **Licence:** Published under MIT in `composer.json`.
- **Requires:** `PHP ^8.4`, `capell-app/admin ^1.0`, `capell-app/ai-orchestrator ^1.0`, `capell-app/core ^1.0.75`.
- **Install:** `composer require capell-app/ai-spend-caps`.

## Quick Start

1. Install the package: `composer require capell-app/ai-spend-caps`.
2. Open the package admin page or resource and verify AI Spend Caps is available.

## For Developers

The package registers one policy guardrail with AI Orchestrator, so every capability run is checked against the limits without changes to the packages that call AI.

## Configure

- **Configuration files:** `config/capell-ai-spend-caps.php`.
- **Admin settings:** `Capell\AiSpendCaps\Settings\SpendCapSettings`.

## Limits And Pitfalls

- Install the required Capell packages at the versions in `composer.json`: `capell-app/admin ^1.0`, `capell-app/ai-orchestrator ^1.0`, `capell-app/core ^1.0.75`.
- Run migrations before opening package resources or public routes.

## Screens And Workflow

Docs gap: add `docs/screenshots.json` before promoting this package with visual workflow claims.

- Admin index screen if the package has a Filament resource.
- Create/edit screen if editors create records.
- Settings/configuration screen when settings exist.
- Frontend output when the package renders public pages.
- Package detail or install intent screen when marketplace-owned.

## Install Impact

- Required packages: `capell-app/admin`, `capell-app/ai-orchestrator`, `capell-app/core`.
- Admin navigation: declares `admin-page: AiSpendCapsAdminPageContribution`; each Filament page or resource controls its own navigation visibility.
- Admin/editor extensions: none declared.
- Permissions: `View:AiUsagePage`.
- Public routes: none declared.
- Database changes: package migrations are declared.
- Config: `config/capell-ai-spend-caps.php`.
- Settings: `Capell\AiSpendCaps\Settings\SpendCapSettings`.
- Queues or schedules: none declared.
- Cache tags: none declared.
- Commands: none declared.

## Troubleshooting

| Symptom | Likely cause | Check | Fix |
| --- | --- | --- | --- |
| Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches |
| Admin screen or command fails on missing table | Package migrations have not run | Check the tables listed in `Data Model` | Run host migrations and rerun the focused package test |

## Upgrading

No manual steps between minor versions.

Read [CHANGELOG.md](CHANGELOG.md) before upgrading.

## Next Steps

- [Package docs](README.md)
- [Overview](overview.md)
- Configuration files: [`config/capell-ai-spend-caps.php`](config/capell-ai-spend-caps.php).
- [Troubleshooting](#troubleshooting)
- [Developer reference](reference.md)
- [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md)
- [Capell documentation design system](../../docs/DESIGN_SYSTEM.md)
- [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md)
- Related packages: [AI Orchestrator](../ai-orchestrator/README.md).

<!-- prettier-ignore-end -->