docs: clarify the price tier comments after frontend review

A tier without a 1h price uses the cache write price that applies to the
tier, which can be the base cache write price. The upsert doc no longer
says a missing cache_write_1h_price clears it, because the generated
TypeScript type requires the key. The price tier note helpers get JSDoc,
and the comments that restated the code or the story are gone.

coderd/aibridge/prices/pricebook/pricebook.go

@@ -28,7 +28,8 @@ type Row struct {
 }
 
 // Tier holds the prices for a request whose prompt is over ThresholdTokens
-// tokens. A nil price uses the price of the Row.
+// tokens. A nil price uses the price of the Row, but a nil CacheWrite1hPrice
+// uses the cache write price that applies to the tier.
 type Tier struct {
 	ThresholdTokens   int64  `json:"threshold_tokens"`
 	InputPrice        *int64 `json:"input_price"`

codersdk/aimodelprices.go

@@ -32,8 +32,8 @@ type AIModelPrice struct {
 
 // AIModelPriceTier holds the prices for a request whose prompt is over
 // ThresholdTokens tokens. Every token of such a request uses the prices of the
-// highest tier it is over. A nil price uses the base price of the model, and a
-// nil CacheWrite1hPrice uses the CacheWritePrice of the tier.
+// highest tier it is over. A nil price uses the base price of the model, but a
+// nil CacheWrite1hPrice uses the cache write price that applies to the tier.
 type AIModelPriceTier struct {
 	ThresholdTokens   int64  `json:"threshold_tokens"`
 	InputPrice        *int64 `json:"input_price"`
@@ -77,8 +77,8 @@ type UpsertAIModelPricesRequest struct {
 }
 
 // AIModelPriceUpsert is one model's prices in an upsert request. It carries
-// only the writable fields of AIModelPrice. A missing or null
-// CacheWrite1hPrice or Tiers clears it.
+// only the writable fields of AIModelPrice. A null CacheWrite1hPrice, or a
+// missing or null Tiers, clears it.
 type AIModelPriceUpsert struct {
 	Provider          string             `json:"provider"`
 	Model             string             `json:"model"`

site/src/api/typesGenerated.ts

@@ -400,8 +400,8 @@ export const AIModelPriceSources: AIModelPriceSource[] = ["custom", "default"];
 /**
  * AIModelPriceTier holds the prices for a request whose prompt is over
  * ThresholdTokens tokens. Every token of such a request uses the prices of the
- * highest tier it is over. A nil price uses the base price of the model, and a
- * nil CacheWrite1hPrice uses the CacheWritePrice of the tier.
+ * highest tier it is over. A nil price uses the base price of the model, but a
+ * nil CacheWrite1hPrice uses the cache write price that applies to the tier.
  */
 export interface AIModelPriceTier {
 	readonly threshold_tokens: number;
@@ -415,8 +415,8 @@ export interface AIModelPriceTier {
 // From codersdk/aimodelprices.go
 /**
  * AIModelPriceUpsert is one model's prices in an upsert request. It carries
- * only the writable fields of AIModelPrice. A missing or null
- * CacheWrite1hPrice or Tiers clears it.
+ * only the writable fields of AIModelPrice. A null CacheWrite1hPrice, or a
+ * missing or null Tiers, clears it.
  */
 export interface AIModelPriceUpsert {
 	readonly provider: string;

site/src/modules/aiModels/PriceTierNotes.tsx

@@ -10,9 +10,11 @@ const formatLabeledPrice = (label: string, micros: number | null): string => {
 	return `${label} ${price.belowThreshold ? "<$" : "$"}${price.value}`;
 };
 
-// The 1h entry is listed when the model or the tier prices 1h writes apart.
-// A tier without a 1h price bills 1h writes at its own cache write price, not
-// at the base 1h price.
+/**
+ * Formats the note for one long-context tier of a price row. A tier without a
+ * 1h price bills 1h writes at its own cache write price, not at the base 1h
+ * price.
+ */
 export const formatTierNote = (
 	base: AIModelPrice,
 	tier: AIModelPriceTier,
@@ -41,6 +43,7 @@ export const formatTierNote = (
 	return `Over ${tier.threshold_tokens.toLocaleString("en-US")} prompt tokens: ${prices.join(" · ")}`;
 };
 
+/** One note per long-context price tier of a price row. */
 export const PriceTierNotes: React.FC<{ price: AIModelPrice }> = ({
 	price,
 }) => (

site/src/pages/AISettingsPage/ModelsPage/components/ModelForm.stories.tsx

@@ -883,8 +883,6 @@ export const CostEstimateRowWinsOverCatalog: Story = {
 	},
 };
 
-// The 1h field appears after the four base prices, followed by one note for
-// each long-context tier.
 export const CostEstimateWithCacheWrite1hAndTiers: Story = {
 	args: {
 		editingModel: mockClaude,