SpecGraph Tokens (SGT)
How SpecGraph Tokens are calculated, the full cost schedule for every AI action, and the token lifecycle.
SpecGraph Tokens (SGT)
SpecGraph Token (SGT) is the unit of platform currency. Every billable AI action has a cost in SGT, deducted from your organization's monthly balance.
How Token Cost Is Calculated
Every action's cost has two components:
- Foundation Cost — A fixed SGT amount per action type, reflecting the platform's compute, orchestration, and infrastructure overhead for that step
- AI Consumption Cost — A variable cost derived from the actual LLM tokens used during the action
The Formula
SGT cost = foundation_cost + ceil(llm_tokens_consumed / 1000)foundation_cost— fixed SGT per action (see schedule below)llm_tokens_consumed— total input + output tokens from the LLM call(s)- Dividing by 1,000 converts raw LLM tokens to SGT (1 SGT ≈ 1,000 LLM tokens)
ceil()rounds up — partial units always count as 1 SGT
Example: PRD Generation
| Component | Value |
|---|---|
| Foundation cost | 60 SGT |
| LLM tokens used | 45,000 |
| AI consumption cost | ceil(45,000 / 1,000) = 45 SGT |
| Total cost | 105 SGT |
Foundation Cost Schedule
Core Workflow Actions
These actions are triggered as you move a project through its phases:
| Phase | Action | Foundation Cost | Typical AI Cost | Typical Total |
|---|---|---|---|---|
| Gathering | Document parsing | 5 SGT | 0 SGT | 5 SGT |
| Generating | PRD generation | 60 SGT | 40–60 SGT | 100–120 SGT |
| Surveying | Survey question generation (per dept) | 10 SGT | 8–15 SGT | 18–25 SGT |
| Surveying | Convert answers to wishes (per dept) | 8 SGT | 5–10 SGT | 13–18 SGT |
| Surveying | Wish clustering | 10 SGT | 8–12 SGT | 18–22 SGT |
| Surveying | Acceptance criteria generation | 8 SGT | 5–10 SGT | 13–18 SGT |
| Resolving | Conflict detection | 20 SGT | 15–25 SGT | 35–45 SGT |
| Resolving | Impact analysis (per conflict) | 5 SGT | 3–8 SGT | 8–13 SGT |
| Unifying | Unification (3 strategy proposals) | 30 SGT | 25–40 SGT | 55–70 SGT |
| Approving | Executive summary generation | 10 SGT | 8–12 SGT | 18–22 SGT |
| Agents | Agent generation (5 agents) | 25 SGT | 15–25 SGT | 40–50 SGT |
| Architecting | Architecture planning | 20 SGT | 15–20 SGT | 35–40 SGT |
| Story Sharding | Story sharding | 20 SGT | 15–25 SGT | 35–45 SGT |
| Exported | Export generation (8 files) | 15 SGT | 10–20 SGT | 25–35 SGT |
Auxiliary Actions
These actions can be triggered at any time, independent of the current project phase:
| Action | Foundation Cost | Typical AI Cost |
|---|---|---|
| Preview wish impact on PRD | 5 SGT | 3–8 SGT |
| Improve text (AI rewrite) | 3 SGT | 2–5 SGT |
| Generate project context | 8 SGT | 5–10 SGT |
| Generate CLAUDE.md | 10 SGT | 8–12 SGT |
| Generate control manifest | 10 SGT | 8–12 SGT |
| Analyze deviations (post-build feedback) | 15 SGT | 10–20 SGT |
| Extract knowledge (project close-out) | 15 SGT | 10–20 SGT |
Foundation costs can be updated by a system admin at any time via Admin → Token Costs without a deployment. The updated value takes effect immediately for new actions.
The Token Lifecycle
Pre-Flight Check (Before Every AI Action)
Before any LLM call is made, the system runs a balance check:
1. User triggers action (e.g. "Generate PRD")
2. System looks up foundation_cost for the action
3. System estimates AI cost based on input size
4. estimated_total = foundation_cost + estimated_ai_cost
5. IF remaining_balance < estimated_total → action is BLOCKED
6. ELSE → estimated_total is RESERVED (optimistic hold)
7. Proceed with the AI actionThis means you will never be surprised by a charge you can't afford — the action won't run if there isn't enough budget.
Settlement (After Completion)
1. Action completes
2. Actual LLM token usage is captured from the AI SDK response
3. actual_cost = foundation_cost + ceil(actual_llm_tokens / 1000)
4. Reservation is released; actual_cost is deducted from balance
5. Full transaction is logged to the audit trailRefund on Failure
If an AI action fails (network error, LLM timeout, validation error), the reservation is fully released — 0 SGT is deducted. The balance is restored automatically.
Background Jobs (Inngest)
Long-running actions like PRD generation run as durable background jobs:
- Reservation is created when you click the button (in the API route)
- Settlement happens when the background job completes (with actual LLM usage)
- Release happens automatically if the job fails at any step
This means the token hold is in place for the duration of the job. You'll see a "reserved" indicator if you check your balance while a job is running.
Estimation Heuristics
The system uses these formulas to estimate cost before running (for the pre-flight check):
| Action | Estimation Formula |
|---|---|
| PRD generation | 60 + ceil(total_document_chars / 1,000) |
| Survey questions | 10 + ceil(prd_section_count × 2) |
| Conflict detection | 20 + ceil(wish_count × 0.5) |
| Unification | 30 + ceil((wishes + conflicts) × 0.8) |
| Agent generation | 25 + ceil(prd_section_count × 1.5) |
| Story sharding | 20 + ceil(prd_section_count × 1.5) |
| All others | foundation_cost × 2 |
Estimates are intentionally conservative. If the estimate exceeds your balance, the action is blocked — even if the actual cost would have been lower. This avoids partial executions.
What Doesn't Cost Tokens
The following actions are always free, regardless of subscription status:
- Viewing any page (projects, PRDs, wishes, conflicts, etc.)
- Adding comments on PRD sections or conflicts
- Voting on wishes
- Manually editing PRD section content
- Approving or rejecting PRDs
- Managing team members, departments, and organization settings
- Uploading documents (the upload itself is free; parsing costs 5 SGT)
- Viewing the requirements graph
- Using the MCP server to read project data