Add toString() options and clamping methods to Money docs

Author: mhluongo

apps/docs/content/docs/ai-guide.mdx

@@ -3,7 +3,7 @@ title: AI Reference
 description: Compact reference for AI code generation
 ---
 
-> This page is optimized for AI assistants. For detailed documentation, see [Getting Started](/docs/getting-started).
+**NOTE:** This page is optimized for AI assistants. For detailed documentation, see [Getting Started](/docs/getting-started).
 
 ## Installation
 
@@ -45,9 +45,9 @@ Money(100.5) // Works but warns about precision loss
 const price = Money("$1234.56")
 
 price.toString() // "$1,234.56"
-price.toString({ symbol: false }) // "1,234.56"
-price.toString({ grouping: false }) // "$1234.56"
-price.toString({ decimals: 0 }) // "$1,235"
+price.toString({ excludeCurrency: true }) // "1,234.56"
+price.toString({ compact: true }) // "$1K"
+price.toString({ maxDecimals: 0 }) // "$1,235"
 price.toString({ locale: "de-DE" }) // "1.234,56 $"
 ```
 

apps/docs/content/docs/api/fixed-point.mdx

@@ -3,7 +3,7 @@ title: FixedPoint & Rational
 description: Arbitrary-precision numeric types for financial calculations
 ---
 
-> **Note:** Most users won't need these types directly. The `Money` class handles precision automatically. These are useful for advanced calculations or when you need raw numeric operations without currency semantics.
+**Note:** Most users won't need these types directly. The `Money` class handles precision automatically. These are useful for advanced calculations or when you need raw numeric operations without currency semantics.
 
 cent provides two numeric types beyond `Money` for precise mathematical operations.
 

apps/docs/content/docs/api/money.mdx

@@ -229,9 +229,59 @@ const cents = amount.roundTo(2, Round.HALF_EVEN)
 const whole = amount.roundTo(0, Round.FLOOR)
 ```
 
+## Clamping Methods
+
+### clamp(min, max)
+
+Constrain a value within a range.
+
+```typescript
+Money("$50").clamp("$0", "$100")   // $50.00 (within bounds)
+Money("-$50").clamp("$0", "$100")  // $0.00 (below min, clamped up)
+Money("$150").clamp("$0", "$100")  // $100.00 (above max, clamped down)
+
+// With Money instances
+const min = Money("$10")
+const max = Money("$1000")
+price.clamp(min, max)
+
+// With numbers (interpreted in same currency)
+price.clamp(0, 100)
+```
+
+### atLeast(min)
+
+Ensure a minimum value.
+
+```typescript
+Money("$50").atLeast("$0")   // $50.00 (already above min)
+Money("-$50").atLeast("$0")  // $0.00 (raised to min)
+
+// Ensure non-negative amounts
+const safeAmount = amount.atLeast(0)
+
+// With Money instance
+Money("$25").atLeast(Money("$50"))  // $50.00
+```
+
+### atMost(max)
+
+Ensure a maximum value.
+
+```typescript
+Money("$50").atMost("$100")   // $50.00 (already below max)
+Money("$150").atMost("$100")  // $100.00 (reduced to max)
+
+// Cap at maximum allowed amount
+const cappedAmount = amount.atMost("$10000")
+
+// With Money instance
+Money("$75").atMost(Money("$50"))  // $50.00
+```
+
 ## Formatting Methods
 
-### toString()
+### toString(options?)
 
 Format as a string with currency symbol.
 
@@ -240,6 +290,39 @@ Money("$100.50").toString() // "$100.50"
 Money("0.5 BTC").toString() // "0.50000000 BTC"
 ```
 
+**Options:**
+
+```typescript
+const price = Money("$1234.567")
+
+// Locale formatting
+price.toString({ locale: "de-DE" }) // "1.234,57 $"
+
+// Compact notation
+Money("$1500000").toString({ compact: true }) // "$1.5M"
+
+// Control decimal places
+price.toString({ maxDecimals: 2 }) // "$1,234.57"
+price.toString({ minDecimals: 4 }) // "$1,234.5670"
+
+// Exclude currency symbol
+price.toString({ excludeCurrency: true }) // "1,234.567"
+
+// Rounding mode for formatting
+price.toString({ maxDecimals: 2, roundingMode: Round.FLOOR }) // "$1,234.56"
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `locale` | `string` | Display locale (default "en-US") |
+| `compact` | `boolean` | Use compact notation (e.g., $1M) |
+| `maxDecimals` | `number` | Maximum decimal places to display |
+| `minDecimals` | `number` | Minimum decimal places (forces trailing zeros) |
+| `excludeCurrency` | `boolean` | Exclude currency symbol/code |
+| `preferSymbol` | `boolean` | Prefer symbol over code for non-ISO currencies |
+| `preferredUnit` | `string` | Preferred fractional unit (e.g., "sat" for BTC) |
+| `roundingMode` | `RoundingMode` | Rounding mode for formatting |
+
 ### toJSON()
 
 Return JSON-serializable representation.