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

# Cost-aware skill

> Budget guardrails for autonomous agents. Cap spend, prefer cheap models when 'good enough' is good enough.

The `cost-aware` skill is what you load when an agent will run
unattended, a cron'd job, a long autonomous task, anything where the
human isn't reviewing each render before it fires.

It doesn't replace the other skills; it composes with them. Load
`storyteller` or `multi-clip` for the *how*, then layer `cost-aware`
on top for the *how much*.

## What it does

* Enforces a per-task budget the agent must not exceed.
* Picks the cheapest model that meets the brief's quality bar.
* Refuses retries that would push past the budget.
* Reports cost per render to the user (or the orchestrator) so trends
  are visible.

## The skill body

```markdown theme={null}
---
name: lavendly-cost-aware
description: Add budget discipline to any Lavendly task.
trigger: Always active when running unattended or when the user mentions budget.
priority: high
---

# Lavendly · Cost-aware

## Pre-flight budget check

Before any paid call:

1. `get_ledger` → record `available` credits.
2. `get_monthly_usage` → record `fraction_used`. If `> 0.85`, refuse
   non-critical renders and notify.
3. Estimate the task's cost from the brief:
   - Single 5 s shot: ~5-10 credits
   - Multi-clip 30 s: ~30-60 credits
   - Voiceover 30 s: ~2 credits
   - Music 30 s: ~3 credits
4. If estimate > available, halt and report.
5. If estimate > 0.30 × available, ask for confirmation before
   spending. (Don't drain the user's balance on one task.)

## Model selection

When `create_workflow` accepts a `videoModel` option:

- Prefer the cheapest model in `get_status.models.video` unless the
  brief explicitly asks for cinematic quality.
- For shots without faces, the cheapest model is almost always
  sufficient.
- For shots with people, jump to a mid-tier only if the cheapest
  model produces visible artifacts.

## Retry discipline

- On render failure, refund automatically (the platform does this,
  but verify with `get_ledger`).
- Maximum 2 retries per render with the same idempotency key. After
  that, report failure and stop, three failures usually means a
  prompt problem, not a transient error.
- NEVER retry by generating a new idempotency key. That's how you
  double-charge.

## Reporting

After each render, emit a single-line summary:

```

\[Lavendly] rendered "${name}", ${duration}s, ${credits_used}cr,
${result.video_url}

```

If the operator passed a webhook URL in the task brief, POST the same
summary there.
```

## Layering with other skills

When both `cost-aware` and `storyteller` are loaded, the agent merges
the rules:

* `storyteller` says "use `mix` audio with native volume 0.6."
* `cost-aware` says "prefer the cheapest model."

The agent uses the cheapest model AND configures the mix correctly.
Skills are additive; there's no precedence conflict because each one
constrains different decisions.

## Try it

Load `storyteller` + `cost-aware` in your runtime, then schedule:

```
Every Monday at 9 AM, generate a 5-second teaser for whatever's
trending in #design today. Budget: 10 credits per teaser. Post the
URL to the team channel.
```

The agent runs unattended. Stays under budget. Reports back. Skips
the week entirely if the monthly cost cap is approaching.