Skip to content

docs: state the generation cost discipline in the README - #38

Merged
Orkas-AI merged 1 commit into
mainfrom
docs/readme-cost-discipline
Sep 22, 2026
Merged

Orkas-AI merged 1 commit into
mainfrom
docs/readme-cost-discipline

Conversation

@leochenpm

Copy link
Copy Markdown
Collaborator

Why

The README already says the compose/edit trunk is zero-key and that generation is BYO. What it never says is what this repo does to keep that generation bill small — cost and billable appear zero times in it, while the skills enforce a fairly specific budget policy.

That gap matters outside the repo too: when someone asks an assistant "what keeps an agentic video tool from burning my provider credits", there is nothing here for it to quote.

What this adds

One section after BYO generation providers, drawn only from what this repo actually enforces:

Claim in the section Where it is enforced
~90% of the result with zero billable generation; compose cheapest for text, generate a last resort packages/skills/stage-plan/SKILL.md
Keyframe cost gate — a shot whose start and end look alike needs one keyframe, not two packages/skills/stage-generate/SKILL.md
Default caps: ≤ 6 generated shots, ≤ 3 recurring characters, one ratio per run; larger runs state the billable count first packages/skills/stage-generate/SKILL.md
cost_estimate.billable_generations must equal the source:"generate" segment count or validation fails packages/skills/stage-plan/SKILL.md
Partial batches preserve completed siblings — a revision re-bills one segment, not the montage packages/skills/stage-generate/SKILL.md

What it deliberately does not claim

  • No price guarantee. The section closes by saying you are billed by your own provider and this repo never sees the invoice.
  • Nothing from the host app leaked in. Orkas-managed credits and the Gate C credit quote never sync here — sync-rules.json keeps account, credits and managed routes host-only — so none of that is described as if it existed in OVS.

Checks

  • pnpm test — 282 passed, 12 skipped
  • No new CLI surface is referenced (only existing skill names and plan fields), so the cli-smoke command contract is untouched
  • Markdown structure verified: code fences balanced, no unclosed table rows

🤖 Generated with Claude Code

The README already tells you the compose and edit trunk is zero-key and
that generation is BYO. What it never says is what the skills do to keep
that generation bill small -- "cost" and "billable" appear zero times in
it, while the skills enforce a fairly specific budget policy.

Adds a section after BYO generation providers, drawn only from what this
repo actually enforces:

- stage-plan aims for ~90% of the result with zero billable generation;
  compose is the cheapest source for anything textual and generate is the
  last resort (packages/skills/stage-plan/SKILL.md).
- The keyframe cost gate: a shot whose start and end look alike needs one
  keyframe, not two (packages/skills/stage-generate/SKILL.md).
- Default caps of 6 generated shots and 3 recurring characters, with the
  billable count stated before anything larger runs.
- cost_estimate.billable_generations must equal the generate-segment
  count or validation fails.
- Partial batches preserve completed siblings, so a revision re-bills one
  segment rather than the montage.

Nothing from the host app leaked in: Orkas-managed credits and Gate C
quotes never sync here (sync-rules.json keeps account, credits and
managed routes host-only), so the section claims no price guarantee --
only that the expensive path is the one you have to ask for.

No new CLI surface is referenced, so the cli-smoke contract is untouched.
pnpm test: 282 passed, 12 skipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Orkas-AI
Orkas-AI merged commit c0c3c3e into main Sep 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants