From 35427c0d78805775a0851d8cd25104e5a2f4164b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Jun 2026 01:01:45 +0000
Subject: [PATCH 1/3] docs: add AI Credits migration notes to blogs and ADRs

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/adr/27137-add-ambient-context-metric.md  |  3 ++
 ...-fallback-audit-metrics-without-aw-info.md |  3 ++
 ...calls-and-tokens-per-turn-in-audit-diff.md |  3 ++
 ...e-carlo-projection-for-forecast-command.md |  3 ++
 ...pers-and-normalize-entity-helper-naming.md |  3 ++
 ...and-default-prefix-keys-and-null-delete.md |  3 ++
 ...-derive-effective-tokens-from-raw-usage.md |  3 ++
 ...entralize-effective-token-limit-parsing.md |  3 ++
 .../docs/blog/2026-05-11-weekly-update.md     |  3 ++
 .../docs/blog/2026-05-26-agent-of-the-day.md  |  3 ++
 .../docs/blog/2026-05-27-agent-of-the-day.md  |  3 ++
 .../docs/blog/2026-05-28-agent-of-the-day.md  |  3 ++
 .../blog/2026-06-01-agent-of-the-day-2.md     |  3 ++
 .../docs/blog/2026-06-01-weekly-update.md     |  3 ++
 docs/src/content/docs/reference/audit.md      | 14 ++++++---
 docs/src/content/docs/reference/footers.md    |  2 +-
 .../docs/reference/frontmatter-full.md        | 31 +++++++++++++------
 .../content/docs/reference/safe-outputs.md    |  4 +--
 .../docs/specs/forecast-specification.md      |  5 ++-
 .../docs/specs/model-alias-specification.md   |  2 +-
 scripts/generate-model-tables.js              | 12 +++----
 21 files changed, 86 insertions(+), 26 deletions(-)

diff --git a/docs/adr/27137-add-ambient-context-metric.md b/docs/adr/27137-add-ambient-context-metric.md
index d15d6e8178b..a6b6eb38377 100644
--- a/docs/adr/27137-add-ambient-context-metric.md
+++ b/docs/adr/27137-add-ambient-context-metric.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/28003-fallback-audit-metrics-without-aw-info.md b/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
index c62ca549c46..0600899d30d 100644
--- a/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
+++ b/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: pelikhan
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md b/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
index f704644a248..7f5ad0b0f48 100644
--- a/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
+++ b/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/31377-monte-carlo-projection-for-forecast-command.md b/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
index 1f97ca4ecdf..e666d98820b 100644
--- a/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
+++ b/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: Unknown (PR authored by `app/copilot-swe-agent`; human deciders TBD)
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md b/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
index c31ca8c95e0..feeb76c70a4 100644
--- a/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
+++ b/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md b/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
index 356fbba87bd..c28d625cd86 100644
--- a/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
+++ b/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
@@ -4,6 +4,9 @@
 **Status**: Draft
 **Deciders**: PR author (pelikhan), reviewers of PR #35338
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 ## Part 1 — Narrative (Human-Friendly)
diff --git a/docs/adr/36421-derive-effective-tokens-from-raw-usage.md b/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
index e5ed73d8664..80cdae03008 100644
--- a/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
+++ b/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
@@ -35,6 +35,9 @@ Recompute ET once when usage is written and persist the corrected value. Rejecte
 - Reporting/output shape is unchanged; only the *source* of the ET value changed.
 - The unknown-model fallback multiplier (`1.0`) and longest-prefix matching behavior are preserved.
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 *This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/26805931606) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*
diff --git a/docs/adr/36496-centralize-effective-token-limit-parsing.md b/docs/adr/36496-centralize-effective-token-limit-parsing.md
index 84386029427..7f626ef1eb2 100644
--- a/docs/adr/36496-centralize-effective-token-limit-parsing.md
+++ b/docs/adr/36496-centralize-effective-token-limit-parsing.md
@@ -34,6 +34,9 @@ Accept short-form only at validation time and have the schema (or a pre-processi
 - Documentation now defaults to short-form notation, so existing long-form examples in user workflows differ stylistically from the docs (both remain valid).
 - Schema default values remain expressed as plain integers (`25000000`) even though docs prefer `25M`.
 
+
+> **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
+
 ---
 
 *This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/26837141982) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*
diff --git a/docs/src/content/docs/blog/2026-05-11-weekly-update.md b/docs/src/content/docs/blog/2026-05-11-weekly-update.md
index 2a7b381c444..5769eb2a043 100644
--- a/docs/src/content/docs/blog/2026-05-11-weekly-update.md
+++ b/docs/src/content/docs/blog/2026-05-11-weekly-update.md
@@ -6,6 +6,9 @@ authors:
 date: 2026-05-11
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 It was a busy week in [github/gh-aw](https://github.com/github/gh-aw)! Four releases landed between May 4 and May 7, paired with a wave of pull requests that delivered new commands, security hardening, and developer-experience polish. Here's everything that shipped.
 
 ## Releases This Week
diff --git a/docs/src/content/docs/blog/2026-05-26-agent-of-the-day.md b/docs/src/content/docs/blog/2026-05-26-agent-of-the-day.md
index cca9e007113..d6d4919ad33 100644
--- a/docs/src/content/docs/blog/2026-05-26-agent-of-the-day.md
+++ b/docs/src/content/docs/blog/2026-05-26-agent-of-the-day.md
@@ -9,6 +9,9 @@ metadata:
   linkedPostText: "How we track Copilot agent PR performance with a daily analysis workflow"
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 Every morning someone at GitHub opens their laptop and wonders: how well did the coding agents do yesterday? Did they ship? Did they stall? Did they create more work than they saved? These questions used to require manual spelunking through dashboards, cross-referencing merged PRs with author names, and guessing at patterns from vibes alone.
 
 Not anymore.
diff --git a/docs/src/content/docs/blog/2026-05-27-agent-of-the-day.md b/docs/src/content/docs/blog/2026-05-27-agent-of-the-day.md
index 6c6ea348d7a..b652523f16d 100644
--- a/docs/src/content/docs/blog/2026-05-27-agent-of-the-day.md
+++ b/docs/src/content/docs/blog/2026-05-27-agent-of-the-day.md
@@ -9,6 +9,9 @@ metadata:
   linkedPostText: "Agent Performance Analyzer hits 90/100 ecosystem health"
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 Every day, 236 agentic workflows run inside the `gh-aw` repository. Most complete quietly. A few fail in patterns worth tracking. And once a week, one workflow reads the entire fleet, scores it, and writes up what it found. That workflow is the **Agent Performance Analyzer**, and its run on May 27, 2026 produced the clearest signal in months.
 
 ## Agent of the Day: Agent Performance Analyzer — Meta-Orchestrator
diff --git a/docs/src/content/docs/blog/2026-05-28-agent-of-the-day.md b/docs/src/content/docs/blog/2026-05-28-agent-of-the-day.md
index 9740c270ad9..4de61335fe4 100644
--- a/docs/src/content/docs/blog/2026-05-28-agent-of-the-day.md
+++ b/docs/src/content/docs/blog/2026-05-28-agent-of-the-day.md
@@ -9,6 +9,9 @@ metadata:
   linkedPostText: "Dead Code Removal Agent hits 100 automated runs"
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 Every codebase accumulates sediment. A helper function that made sense six months ago. A wrapper that lost its reason to exist after a refactor. Nobody deletes it on purpose — it just lingers. In Go, that lingering costs you: extra surface area to maintain, test coverage for code that does nothing new, and cognitive overhead for every engineer who reads the file.
 
 The **Dead Code Removal Agent** is a scheduled GitHub Actions workflow that runs daily on the `gh-aw` repository. Its job is simple: find unused code, verify nothing breaks, and open a pull request. No human intervention required until review time.
diff --git a/docs/src/content/docs/blog/2026-06-01-agent-of-the-day-2.md b/docs/src/content/docs/blog/2026-06-01-agent-of-the-day-2.md
index 64b46925111..e183e78107f 100644
--- a/docs/src/content/docs/blog/2026-06-01-agent-of-the-day-2.md
+++ b/docs/src/content/docs/blog/2026-06-01-agent-of-the-day-2.md
@@ -9,6 +9,9 @@ metadata:
   linkedPostText: "Catch architectural drift automatically with Architecture Guardian"
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 ## 🏗️ Agent of the Day: Architecture Guardian
 
 Architectural drift is quiet and cumulative. A file grows past 600 lines. A function absorbs one more responsibility. An import cycle sneaks in between two packages that "just need to share a little logic." None of it trips a CI gate, no test turns red, and six months later a new engineer opens that directory and wonders how it got this bad. The Architecture Guardian workflow exists precisely to interrupt that pattern before it becomes load-bearing.
diff --git a/docs/src/content/docs/blog/2026-06-01-weekly-update.md b/docs/src/content/docs/blog/2026-06-01-weekly-update.md
index f4567d2ea0f..1fced28efad 100644
--- a/docs/src/content/docs/blog/2026-06-01-weekly-update.md
+++ b/docs/src/content/docs/blog/2026-06-01-weekly-update.md
@@ -6,6 +6,9 @@ authors:
 date: 2026-06-01
 ---
 
+> [!NOTE]
+> This post references historical **Effective Tokens (ET)** metrics. gh-aw now uses **AI Credits (AIC)** as the primary cost metric.
+
 It's been a busy week in [github/gh-aw](https://github.com/github/gh-aw)! Five releases landed between May 28 and May 31, capped off by [v0.77.4](https://github.com/github/gh-aw/releases/tag/v0.77.4) — one of the biggest releases in recent memory. Here's everything that shipped.
 
 ## Release: v0.77.4
diff --git a/docs/src/content/docs/reference/audit.md b/docs/src/content/docs/reference/audit.md
index d19b2ea264c..81b1d902105 100644
--- a/docs/src/content/docs/reference/audit.md
+++ b/docs/src/content/docs/reference/audit.md
@@ -7,6 +7,9 @@ sidebar:
 
 The `gh aw audit` commands download workflow run artifacts and logs, analyze MCP tool usage and network behavior, and produce structured reports suited for security reviews, debugging, and feeding to AI agents.
 
+> [!NOTE]
+> AI Credits (AIC) are the primary spend metric in gh-aw. Legacy Effective Tokens (ET) fields remain available for backward compatibility in report output.
+
 ## `gh aw audit <run-id-or-url> [<run-id-or-url>...]`
 
 Audit one or more workflow runs. When a single run is provided, a detailed Markdown report is generated. When two or more runs are provided, the first is used as the base (reference) run and the remaining runs are compared against it, producing a diff report.
@@ -82,7 +85,7 @@ gh aw audit 12345 12346 --repo owner/repo      # Specify repository
 The Metrics section includes an `ambient_context` object when available. Ambient context captures the first LLM inference footprint for the run:
 - `ambient_context.input_tokens` — input tokens for the first invocation
 - `ambient_context.cached_tokens` — cache-read tokens reused by the first invocation
-- `ambient_context.effective_tokens` — `input_tokens + cached_tokens`
+- `ambient_context.effective_tokens` — legacy ET field (`input_tokens + cached_tokens`) retained for compatibility
 
 **Diff output** includes:
 - New and removed network domains
@@ -91,8 +94,8 @@ The Metrics section includes an `ambient_context` object when available. Ambient
 - Anomaly flags (new denied domains, previously-denied domains now allowed)
 - MCP tool invocation changes (new/removed tools, call count and error count diffs)
 - Run metrics comparison (token usage, duration, turns)
-- Token usage and spend breakdown: input tokens, output tokens, cache read/write tokens, effective tokens, AIC, total API requests, and cache efficiency per run
-- Tokens per turn: effective tokens divided by turn count for each run, with the change between runs
+- Token usage and spend breakdown: input tokens, output tokens, cache read/write tokens, AIC, legacy effective tokens (ET), total API requests, and cache efficiency per run
+- Tokens per turn: legacy ET divided by turn count for each run, with the change between runs
 - AIC reporting: AI Credits are shown alongside token metrics for spend tracking
 - Tool call breakdown: per-tool call counts (new, removed, and changed tools) with max input/output sizes
 - Bash command breakdown: aggregated call counts and max input/output sizes for each distinct bash command invoked
@@ -122,7 +125,7 @@ This feature is built into the `gh aw logs` command via the `--format` flag.
 
 The report output includes an executive summary, domain inventory, metrics trends, MCP server health, and per-run breakdown. It detects cross-run anomalies such as domain access spikes, elevated MCP error rates, and connection rate changes.
 
-For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, `effective_tokens`).
+For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, and legacy `effective_tokens`).
 
 **`--stdin` mode:** Pass `--stdin` to supply an explicit list of run IDs or URLs instead of letting the command discover runs from the GitHub API. Date, count, and workflow-name filters are ignored; `--engine`, `--firewall`, `--safe-output`, and other content filters still apply. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`.
 
@@ -146,7 +149,8 @@ gh aw logs --format markdown --repo owner/repo --count 10
 
 - [Cost Management](/gh-aw/reference/cost-management/) — Track AIC-first spend and token usage
 - [Artifacts](/gh-aw/reference/artifacts/) — Artifact names, directory structures, and token usage file locations (`token-usage.jsonl` in `firewall-audit-logs`)
-- [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) — Legacy effective token computation details
+- [AI Credits Specification](/gh-aw/specs/ai-credits-specification/) — Primary AIC computation details
+- [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) — Legacy ET computation details
 - [Network](/gh-aw/reference/network/) — Firewall and domain allow/deny configuration
 - [MCP Gateway](/gh-aw/reference/mcp-gateway/) — MCP server health and debugging
 - [CLI Commands](/gh-aw/setup/cli/) — Full CLI reference
diff --git a/docs/src/content/docs/reference/footers.md b/docs/src/content/docs/reference/footers.md
index 979a32dbb3d..0718cda6144 100644
--- a/docs/src/content/docs/reference/footers.md
+++ b/docs/src/content/docs/reference/footers.md
@@ -83,7 +83,7 @@ safe-outputs:
     title-prefix: "[bot] "
 ```
 
-The `messages.footer` template supports variables like `{workflow_name}`, `{agentic_workflow_url}`, `{run_url}`, `{triggering_number}`, `{effective_tokens_suffix}`, and more. `{agentic_workflow_url}` links directly to the agentic workflow file view for the run (equivalent to `{run_url}/agentic_workflow`), while `{run_url}` links to the plain Actions run page. `{effective_tokens_suffix}` is a pre-formatted, always-safe suffix (e.g. `" · sonnet46 1.2K"` or `""`) that you can place directly before `{history_link}`. When the run's engine model is known, the suffix is prefixed with a deterministic compact model identifier (`sonnet46`, `gpt55`, `opus47`, `haiku45`, `gem25`, …), and direct short aliases like `opus`, `sonnet`, and `haiku` are preserved. See [Custom Messages](/gh-aw/reference/safe-outputs/#custom-messages-messages) for complete documentation on message templates and available variables.
+The `messages.footer` template supports variables like `{workflow_name}`, `{agentic_workflow_url}`, `{run_url}`, `{triggering_number}`, `{ai_credits_suffix}`, and more. `{agentic_workflow_url}` links directly to the agentic workflow file view for the run (equivalent to `{run_url}/agentic_workflow`), while `{run_url}` links to the plain Actions run page. `{ai_credits_suffix}` is a pre-formatted, always-safe suffix (e.g. `" · sonnet46 12.4 AIC"` or `""`) that you can place directly before `{history_link}`. When the run's engine model is known, the suffix is prefixed with a deterministic compact model identifier (`sonnet46`, `gpt55`, `opus47`, `haiku45`, `gem25`, …), and direct short aliases like `opus`, `sonnet`, and `haiku` are preserved. Legacy templates that still use `{effective_tokens_suffix}` continue to work for backward compatibility. See [Custom Messages](/gh-aw/reference/safe-outputs/#custom-messages-messages) for complete documentation on message templates and available variables.
 
 ## Related Documentation
 
diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index bec17a085fc..356780cf646 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -2226,7 +2226,7 @@ engine:
   # (optional)
   api-target: "example-value"
 
-  # Custom model token weights for effective token computation. Overrides or extends
+  # Custom model token weights for legacy Effective Tokens (ET) computation. Overrides or extends
   # the built-in model multipliers from model_multipliers.json. Useful for custom
   # models or adjusted cost ratios.
   # (optional)
@@ -2529,19 +2529,30 @@ engine:
   # the default engine when engine.id is not specified.
   model: "example-value"
 
-# Explicit ET budget control for firewall cost enforcement. Omit this field to
-# leave ET budget protection unset. Set to a negative value to disable budget
-# enforcement and token steering.
+# Explicit AI Credits budget control for firewall cost enforcement. Omit this
+# field to leave AIC budget protection unset. Set to -1 to disable budget
+# enforcement.
 # (optional)
 # Accepted formats:
 
-# Format 1: Maximum effective-token (ET) budget for AWF API proxy enforcement. Use
-# a negative value to disable budget enforcement and token steering.
-max-effective-tokens: 1
+# Format 1: Maximum AI Credits (AIC) budget for AWF API proxy enforcement.
+max-ai-credits: 1
 
-# Format 2: Maximum effective-token (ET) budget as a numeric string or GitHub
-# Actions expression.
-max-effective-tokens: "example-value"
+# Format 2: Maximum AI Credits (AIC) budget as a numeric string with optional
+# K/M suffix or GitHub Actions expression.
+max-ai-credits: "example-value"
+
+# Explicit daily AI Credits guardrail per workflow across the previous 24-hour
+# window. Omit to disable, or set to -1 to explicitly disable.
+# (optional)
+# Accepted formats:
+
+# Format 1: Maximum daily AI Credits (AIC) budget.
+max-daily-ai-credits: 1
+
+# Format 2: Maximum daily AI Credits (AIC) budget as a numeric string with
+# optional K/M suffix or GitHub Actions expression.
+max-daily-ai-credits: "example-value"
 
 # DEPRECATED: Legacy alias for AWF invocation cap (`apiProxy.maxRuns`).
 # Use `max-turns` instead. Defaults to 500 when omitted.
diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index 7806e35a344..9b72d09b337 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -1650,9 +1650,9 @@ safe-outputs:
 
 The `footer-install` template renders the install instructions that follow the footer attribution line. When a workflow source is available and no custom template is set, the default renders as a collapsed `<details>` disclosure with the summary `Add this agentic workflows to your repo`; the expanded block contains the `gh aw add {workflow_source}` command. Custom `footer-install` overrides bypass the disclosure wrapper, so include `<details>` markup explicitly if you want the same collapsed UX. Supported placeholders: `{workflow_source}`, `{workflow_source_url}`.
 
-**Variables**: `{workflow_name}`, `{run_url}`, `{agentic_workflow_url}`, `{triggering_number}`, `{workflow_source}`, `{workflow_source_url}`, `{event_type}`, `{status}`, `{operation}`, `{effective_tokens}`, `{effective_tokens_formatted}`, `{effective_tokens_suffix}`
+**Variables**: `{workflow_name}`, `{run_url}`, `{agentic_workflow_url}`, `{triggering_number}`, `{workflow_source}`, `{workflow_source_url}`, `{event_type}`, `{status}`, `{operation}`, `{effective_tokens}`, `{effective_tokens_formatted}`, `{ai_credits_suffix}`, `{effective_tokens_suffix}`
 
-`{effective_tokens}` contains the raw total effective token count for the run (e.g. `1200`), and `{effective_tokens_formatted}` is the compact human-readable form (e.g. `1.2K`, `3M`). Both are only present when the effective token count is greater than zero. `{effective_tokens_suffix}` is a pre-formatted, always-safe suffix string (e.g. `" · sonnet46 1.2K"` or `""`) that can be inserted directly into footer templates alongside `{history_link}`. When the run's engine model is known, the suffix is prefixed with a deterministic compact model identifier — `sonnetNN` for Sonnet, `gptNN` for GPT, `opusNN` for Opus, `haikuNN` for Haiku, `gemNN` for Gemini, with a stable fallback for other models. Direct short aliases like `opus`, `sonnet`, and `haiku` are preserved. The default footer automatically includes the formatted value — use these variables in custom footer templates to include token usage in your own format. See [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for details on how effective tokens are computed.
+`{ai_credits_suffix}` is the preferred pre-formatted, always-safe suffix for run cost (for example, `" · sonnet46 12.4 AIC"` or `""`) and can be inserted directly into footer templates alongside `{history_link}`. `{effective_tokens}` and `{effective_tokens_formatted}` remain available as legacy ET compatibility fields. `{effective_tokens_suffix}` is also preserved as a legacy alias for older templates. When the run's engine model is known, the suffix is prefixed with a deterministic compact model identifier — `sonnetNN` for Sonnet, `gptNN` for GPT, `opusNN` for Opus, `haikuNN` for Haiku, `gemNN` for Gemini, with a stable fallback for other models. Direct short aliases like `opus`, `sonnet`, and `haiku` are preserved. The default footer uses AI Credits formatting; use these variables to customize output as needed. See [AI Credits Specification](/gh-aw/specs/ai-credits-specification/) for AIC details and [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for legacy ET computation.
 
 ## Staged Mode
 
diff --git a/docs/src/content/docs/specs/forecast-specification.md b/docs/src/content/docs/specs/forecast-specification.md
index d110f5a9b89..9ee4cabe4a5 100644
--- a/docs/src/content/docs/specs/forecast-specification.md
+++ b/docs/src/content/docs/specs/forecast-specification.md
@@ -14,11 +14,14 @@ sidebar:
 
 > ⚠️ **Experimental**: This specification describes a feature that is under active development. The command interface, output schema, and algorithmic parameters are subject to change without notice. Do not depend on this interface in production workflows.
 
+> [!IMPORTANT]
+> AI Credits (AIC) is the primary cost metric in gh-aw. This draft still references legacy Effective Tokens (ET) field names where command output and schema compatibility require them.
+
 ---
 
 ## Abstract
 
-This specification defines the `gh aw forecast` command for the GitHub Agentic Workflows (gh-aw) project. The command performs historical sampling of completed agentic workflow runs and applies a Monte Carlo simulation engine to project future Effective Token (ET) consumption over a configurable time horizon. The specification covers workflow discovery (local and remote modes), data sampling via the GitHub Actions API, the Poisson–bootstrap Monte Carlo projection algorithm, episode-level analysis, and both console-table and machine-readable JSON output formats. Implementations conforming to this specification provide operators with probabilistic token-consumption forecasts suitable for capacity planning, cost estimation, and budget governance.
+This specification defines the `gh aw forecast` command for the GitHub Agentic Workflows (gh-aw) project. The command performs historical sampling of completed agentic workflow runs and applies a Monte Carlo simulation engine to project future AI Credits (AIC) and legacy Effective Token (ET) consumption over a configurable time horizon. The specification covers workflow discovery (local and remote modes), data sampling via the GitHub Actions API, the Poisson–bootstrap Monte Carlo projection algorithm, episode-level analysis, and both console-table and machine-readable JSON output formats. Implementations conforming to this specification provide operators with probabilistic token-consumption forecasts suitable for capacity planning, cost estimation, and budget governance.
 
 ---
 
diff --git a/docs/src/content/docs/specs/model-alias-specification.md b/docs/src/content/docs/specs/model-alias-specification.md
index 0195e6853f1..5ea07361978 100644
--- a/docs/src/content/docs/specs/model-alias-specification.md
+++ b/docs/src/content/docs/specs/model-alias-specification.md
@@ -74,7 +74,7 @@ This specification covers:
 This specification does NOT cover:
 
 - Engine-specific API call construction (how parameters are forwarded to the provider REST API)
-- Token budgets, cost accounting, or the Effective Tokens metric (see [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/))
+- Token budgets, cost accounting, or AI Credits billing (see [AI Credits Specification](/gh-aw/specs/ai-credits-specification/) and legacy [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/))
 - Model capability detection at runtime
 - Model routing logic within the Copilot gateway
 
diff --git a/scripts/generate-model-tables.js b/scripts/generate-model-tables.js
index 441f3dd02a0..30914807674 100644
--- a/scripts/generate-model-tables.js
+++ b/scripts/generate-model-tables.js
@@ -10,7 +10,7 @@
  *
  * Inputs:
  *   pkg/cli/data/model_aliases.json     – Built-in alias → pattern mappings
- *   pkg/cli/data/model_multipliers.json – Per-model Effective Token multipliers
+ *   pkg/cli/data/model_multipliers.json – Per-model legacy Effective Token multipliers
  *
  * Output:
  *   docs/src/content/docs/reference/model-tables.md
@@ -175,19 +175,19 @@ function generateMarkdown() {
   // Frontmatter
   lines.push("---");
   lines.push("title: Model Aliases & Multipliers");
-  lines.push("description: Reference tables for the built-in model alias map and per-model Effective Token multipliers used by GitHub Agentic Workflows.");
+  lines.push("description: Reference tables for the built-in model alias map and legacy per-model Effective Token multipliers used by GitHub Agentic Workflows.");
   lines.push("sidebar:");
   lines.push("  order: 297");
   lines.push("---");
   lines.push("");
 
-  lines.push("This page lists the built-in model aliases and the per-model Effective Token (ET) multipliers used by GitHub Agentic Workflows.");
+  lines.push("This page lists the built-in model aliases and the legacy per-model Effective Token (ET) multipliers used by GitHub Agentic Workflows. AI Credits (AIC) is the primary cost metric.");
   lines.push("");
 
   // Approximation callout
   lines.push("> [!CAUTION]");
   lines.push(
-    "> The multiplier values shown on this page are **approximations**. They are used solely for the purpose of normalizing token usage across models into a single comparable metric (Effective Tokens) and do **not** represent precise cost ratios. Values may be inaccurate for specific model versions and may become out of date as providers update their offerings. Do not use these numbers for billing or financial calculations."
+    "> The multiplier values shown on this page are **approximations** for legacy ET normalization only. gh-aw uses AI Credits (AIC) as the primary billing metric. Do not use ET multipliers for billing or financial calculations."
   );
   lines.push("");
 
@@ -223,10 +223,10 @@ function generateMarkdown() {
   lines.push("## Model Multipliers");
   lines.push("");
   lines.push(
-    `Effective Token multipliers scale the weighted token total for each model relative to the reference model (\`${referenceModel}\`, multiplier = 1.0). A multiplier of 5.0 means that a run on that model counts as five times as many Effective Tokens as the same run on the reference model.`
+    `Legacy Effective Token multipliers scale the weighted token total for each model relative to the reference model (\`${referenceModel}\`, multiplier = 1.0). A multiplier of 5.0 means that a run on that model counts as five times as many Effective Tokens as the same run on the reference model.`
   );
   lines.push("");
-  lines.push("See the [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for the full formula.");
+  lines.push("See the [AI Credits Specification](/gh-aw/specs/ai-credits-specification/) for primary billing details and the [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for legacy ET formulas.");
   lines.push("");
 
   lines.push("### Token Class Weights");

From d05ebe16b5acf1750d97c30316bb2ca1dbd3b53b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Jun 2026 01:03:48 +0000
Subject: [PATCH 2/3] docs: regenerate model tables with AI Credits guidance

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/model-tables.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/src/content/docs/reference/model-tables.md b/docs/src/content/docs/reference/model-tables.md
index d0605ba027a..22ee0430a40 100644
--- a/docs/src/content/docs/reference/model-tables.md
+++ b/docs/src/content/docs/reference/model-tables.md
@@ -1,14 +1,14 @@
 ---
 title: Model Aliases & Multipliers
-description: Reference tables for the built-in model alias map and per-model Effective Token multipliers used by GitHub Agentic Workflows.
+description: Reference tables for the built-in model alias map and legacy per-model Effective Token multipliers used by GitHub Agentic Workflows.
 sidebar:
   order: 297
 ---
 
-This page lists the built-in model aliases and the per-model Effective Token (ET) multipliers used by GitHub Agentic Workflows.
+This page lists the built-in model aliases and the legacy per-model Effective Token (ET) multipliers used by GitHub Agentic Workflows. AI Credits (AIC) is the primary cost metric.
 
 > [!CAUTION]
-> The multiplier values shown on this page are **approximations**. They are used solely for the purpose of normalizing token usage across models into a single comparable metric (Effective Tokens) and do **not** represent precise cost ratios. Values may be inaccurate for specific model versions and may become out of date as providers update their offerings. Do not use these numbers for billing or financial calculations.
+> The multiplier values shown on this page are **approximations** for legacy ET normalization only. gh-aw uses AI Credits (AIC) as the primary billing metric. Do not use ET multipliers for billing or financial calculations.
 
 ## Model Aliases
 
@@ -66,7 +66,7 @@ Meta-aliases reference other aliases by name. They are resolved recursively unti
 | `mini` | `haiku` → `gpt-5-mini` → `gpt-5-nano` → `gemini-flash-lite` |
 | `large` | `sonnet` → `gpt-5-pro` → `gpt-5` → `gemini-pro` |
 | `agent` | `sonnet-6x` → `gpt-5.4` → `gpt-5.3` → `gemini-pro` → `any` |
-| `small-agent` | `haiku` → `gpt-5-mini` → `gemini-flash` → `any` |
+| `small-agent` | `haiku` → `gpt-5-mini` → `gemini-flash` |
 | `copilot` | `agent` |
 | `claude` | `agent` |
 | `codex` | `agent` |
@@ -75,9 +75,9 @@ Meta-aliases reference other aliases by name. They are resolved recursively unti
 
 ## Model Multipliers
 
-Effective Token multipliers scale the weighted token total for each model relative to the reference model (`claude-sonnet-4.5`, multiplier = 1.0). A multiplier of 5.0 means that a run on that model counts as five times as many Effective Tokens as the same run on the reference model.
+Legacy Effective Token multipliers scale the weighted token total for each model relative to the reference model (`claude-sonnet-4.5`, multiplier = 1.0). A multiplier of 5.0 means that a run on that model counts as five times as many Effective Tokens as the same run on the reference model.
 
-See the [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for the full formula.
+See the [AI Credits Specification](/gh-aw/specs/ai-credits-specification/) for primary billing details and the [Effective Tokens Specification](/gh-aw/specs/effective-tokens-specification/) for legacy ET formulas.
 
 ### Token Class Weights
 

From 89bc7993b4c7f88e6bfa6e23a698f3927fd38bc7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Jun 2026 01:04:57 +0000
Subject: [PATCH 3/3] docs: normalize ADR migration note formatting

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/adr/27137-add-ambient-context-metric.md                     | 1 -
 docs/adr/28003-fallback-audit-metrics-without-aw-info.md         | 1 -
 docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md   | 1 -
 docs/adr/31377-monte-carlo-projection-for-forecast-command.md    | 1 -
 ...ition-and-token-helpers-and-normalize-entity-helper-naming.md | 1 -
 .../adr/35338-env-command-default-prefix-keys-and-null-delete.md | 1 -
 docs/adr/36421-derive-effective-tokens-from-raw-usage.md         | 1 -
 docs/adr/36496-centralize-effective-token-limit-parsing.md       | 1 -
 8 files changed, 8 deletions(-)

diff --git a/docs/adr/27137-add-ambient-context-metric.md b/docs/adr/27137-add-ambient-context-metric.md
index a6b6eb38377..bd9bc3ae5d7 100644
--- a/docs/adr/27137-add-ambient-context-metric.md
+++ b/docs/adr/27137-add-ambient-context-metric.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/28003-fallback-audit-metrics-without-aw-info.md b/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
index 0600899d30d..7635b255b4e 100644
--- a/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
+++ b/docs/adr/28003-fallback-audit-metrics-without-aw-info.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: pelikhan
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md b/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
index 7f5ad0b0f48..0a95547d5ae 100644
--- a/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
+++ b/docs/adr/28494-tool-calls-and-tokens-per-turn-in-audit-diff.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/31377-monte-carlo-projection-for-forecast-command.md b/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
index e666d98820b..70f70c23fa4 100644
--- a/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
+++ b/docs/adr/31377-monte-carlo-projection-for-forecast-command.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: Unknown (PR authored by `app/copilot-swe-agent`; human deciders TBD)
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md b/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
index feeb76c70a4..2fc78777300 100644
--- a/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
+++ b/docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: pelikhan, Copilot
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md b/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
index c28d625cd86..376f8eeee0e 100644
--- a/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
+++ b/docs/adr/35338-env-command-default-prefix-keys-and-null-delete.md
@@ -4,7 +4,6 @@
 **Status**: Draft
 **Deciders**: PR author (pelikhan), reviewers of PR #35338
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/36421-derive-effective-tokens-from-raw-usage.md b/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
index 80cdae03008..39e7f77e67d 100644
--- a/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
+++ b/docs/adr/36421-derive-effective-tokens-from-raw-usage.md
@@ -35,7 +35,6 @@ Recompute ET once when usage is written and persist the corrected value. Rejecte
 - Reporting/output shape is unchanged; only the *source* of the ET value changed.
 - The unknown-model fallback multiplier (`1.0`) and longest-prefix matching behavior are preserved.
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
diff --git a/docs/adr/36496-centralize-effective-token-limit-parsing.md b/docs/adr/36496-centralize-effective-token-limit-parsing.md
index 7f626ef1eb2..f768ad929d1 100644
--- a/docs/adr/36496-centralize-effective-token-limit-parsing.md
+++ b/docs/adr/36496-centralize-effective-token-limit-parsing.md
@@ -34,7 +34,6 @@ Accept short-form only at validation time and have the schema (or a pre-processi
 - Documentation now defaults to short-form notation, so existing long-form examples in user workflows differ stylistically from the docs (both remain valid).
 - Schema default values remain expressed as plain integers (`25000000`) even though docs prefer `25M`.
 
-
 > **Migration note:** This ADR references the legacy Effective Tokens (ET) terminology for historical context. gh-aw now uses AI Credits (AIC) as the primary cost metric.
 
 ---
