docs: usage-cost tracking (last_cost/total_cost prompt vars, default $ segment, cache prices feed cost accounting)

Clients.md

@@ -62,8 +62,8 @@ The `models` array lists the available models from the model client. Each one ha
 | `type`                      | *        | `all`       | The type of model. Coyote supports only 3 types of models: <ul><li>`chat`</li><li>`embedding`</li><li>`reranker`</li></ul>                                                                                                                      |
 | `input_price`               |          | `all`       | The cost in USD per 1M tokens for each input sequence; Coyote will keep track of usage costs if this is defined                                                                                                                                 |
 | `output_price`              |          | `all`       | The cost in USD per 1M tokens of the model output; Coyote will keep track of usage costs if this is defined                                                                                                                                     |
-| `cache_read_price`          |          | `all`       | The cost in USD per 1M tokens for reading prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it                                                                                     |
-| `cache_write_price`         |          | `all`       | The cost in USD per 1M tokens for writing prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it                                                                                     |
+| `cache_read_price`          |          | `all`       | The cost in USD per 1M tokens for reading prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it, and used in usage-cost tracking                                                    |
+| `cache_write_price`         |          | `all`       | The cost in USD per 1M tokens for writing prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it, and used in usage-cost tracking                                                    |
 | `patch`                     |          | `all`       | See the [model-specific patch configuration](Patches#model-specific-patches) documentation                                                                                                                                               |
 | `max_input_tokens`          |          | `all`       | The maximum number of input tokens for the model                                                                                                                                                                                              |
 | `max_output_tokens`         |          | `chat`      | The maximum number of output tokens for the model                                                                                                                                                                                             |
@@ -101,6 +101,9 @@ clients:
 > * Cache activity is visible in the REPL: the default right prompt shows a ⚡ segment with the tokens read from cache
 >   on the most recent call (see the [token usage prompt variables](REPL-Prompt#variables)), and `.info session` shows
 >   cumulative cache reads/writes for the session.
+> * Coyote also tracks the real USD cost of each call (input/output/cache-read/cache-write tokens × the model's
+>   catalog prices): the default right prompt shows the session's running `$` total, and `.info session` / session
+>   exports include `total_cost`. Cost is only reported when every billed component has a known price. No estimates.
 > * Setting `prompt_cache: false` produces request bodies byte-identical to Coyote versions that predate prompt caching.
 
 # Authentication

REPL-Prompt.md

@@ -3,7 +3,7 @@ and `right_prompt` settings in the global Coyote configuration file:
 
 ```yaml
 left_prompt: '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
-right_prompt: '{color.cyan}{?reasoning_effort [{reasoning_effort}] }{color.purple}{?last_cache_read_tokens ⚡{last_cache_read_tokens} }{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
+right_prompt: '{color.cyan}{?reasoning_effort [{reasoning_effort}] }{color.purple}{?last_cache_read_tokens ⚡{last_cache_read_tokens} }{?total_cost ${total_cost} }{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
 ```
 
 > [!NOTE]
@@ -100,6 +100,11 @@ total_input_tokens: 5400          # Cumulative input tokens for the active sessi
 total_output_tokens: 1800         # Cumulative output tokens for the active session
 total_cache_read_tokens: 4100     # Cumulative cache-read tokens for the active session
 total_cache_creation_tokens: 1200 # Cumulative cache-write tokens for the active session
+last_cost: 0.0142              # USD cost of the most recent API call (real usage × the model's catalog prices);
+                               # only set when every billed component has a known price, and hidden until it
+                               # renders as a nonzero 4-decimal amount
+total_cost: 0.3982             # Cumulative USD cost for the active session, accumulated per API call with the
+                               # prices of the model that served each call (accurate across mid-session model switches)
 
 # RAG Variables
 rag: temp                      # The name of the active RAG