update utilities tone

Author: notunderctrl

apps/website/docs/guide/14-useful-utilities/01-rate-imiter.mdx

@@ -1,17 +1,12 @@
 ---
 title: Rate Limiter
-description:
-  Control request frequency with configurable limits and intervals
 ---
 
-# Rate Limiter
+CommandKit provides a rate limiter utility that controls the frequency
+of operations such as user actions or API requests. This helps prevent
+system overload by enforcing configurable request limits.
 
-Think of a rate limiter like a traffic light for your application. It
-controls how often something can happen - like how many times a user
-can click a button or make an API request. This prevents your system
-from being overwhelmed.
-
-## Basic Usage
+## Basic usage
 
 The simplest way to use rate limiting is with the default settings:
 
@@ -29,10 +24,9 @@ if (allowed) {
 }
 ```
 
-## Custom Configuration
+## Custom configuration
 
-Sometimes you need different limits for different situations. You can
-create a custom rate limiter with specific settings:
+You can create a custom rate limiter with specific settings:
 
 ```typescript
 import { createRateLimiter } from 'commandkit/ratelimit';
@@ -46,9 +40,9 @@ const apiLimiter = createRateLimiter({
 const allowed = await apiLimiter.limit('api:endpoint');
 ```
 
-## Advanced Usage
+## Advanced usage
 
-### Checking Remaining Requests
+### Checking remaining requests
 
 You can check how many requests a user has left and when the limit
 resets:
@@ -68,10 +62,9 @@ console.log(
 );
 ```
 
-### Manual Reset
+### Manual reset
 
-In some cases, you might want to reset a user's rate limit (like after
-they upgrade their account):
+You can manually reset a user's rate limit when needed:
 
 ```typescript
 import { resetRateLimit } from 'commandkit/ratelimit';
@@ -80,11 +73,11 @@ import { resetRateLimit } from 'commandkit/ratelimit';
 await resetRateLimit('user:123');
 ```
 
-### Using External Storage
+### Using external storage
 
-By default, rate limiters store data in memory. If you're running
-multiple servers, you'll want to use external storage like Redis so
-all servers can share the same rate limit information:
+Rate limiters store data in memory by default. For multi-server
+deployments, use external storage like Redis to share rate limit data
+across all servers:
 
 ```typescript
 import { RateLimiter, RateLimitStorage } from 'commandkit/ratelimit';
@@ -115,30 +108,8 @@ const limiter = createRateLimiter({
 });
 ```
 
-## Default Settings
+## Default settings
 
 - **Max Requests**: 10 requests
 - **Time Window**: 60 seconds (1 minute)
 - **Storage**: In-memory (works for single-server applications)
-
-## Common Use Cases
-
-- **API Rate Limiting**: Prevent users from making too many API calls
-- **User Action Throttling**: Limit how often users can click buttons
-  or submit forms
-- **Resource Access Control**: Control access to expensive operations
-- **Spam Prevention**: Stop automated bots from overwhelming your
-  system
-
-## Tips for Beginners
-
-1. **Start Simple**: Use the default `ratelimit()` function for basic
-   needs
-2. **Choose Good Keys**: Use descriptive keys like `user:123` or
-   `api:endpoint` to make debugging easier
-3. **Set Reasonable Limits**: Don't make limits too strict or too
-   loose - find the right balance
-4. **Handle Rejection**: Always check if the rate limit allows the
-   action before proceeding
-5. **Consider Your Users**: Think about legitimate use cases when
-   setting limits

apps/website/docs/guide/14-useful-utilities/02-mutex.mdx

@@ -1,17 +1,13 @@
 ---
 title: Mutex
-description:
-  Ensure exclusive access to shared resources with async mutex locks
 ---
 
-# Mutex
+A mutex (mutual exclusion) ensures that only one operation can access
+a shared resource at a time. This prevents race conditions and data
+corruption when multiple operations attempt to modify the same
+resource simultaneously.
 
-A mutex is like a "do not disturb" sign for your data. It ensures that
-only one operation can access a shared resource at a time. Imagine
-multiple people trying to edit the same document - a mutex makes sure
-only one person can edit it at once.
-
-## Basic Usage
+## Basic usage
 
 The easiest way to use a mutex is with the `withMutex` function, which
 automatically handles locking and unlocking:
@@ -26,7 +22,7 @@ const result = await withMutex('shared-resource', async () => {
 });
 ```
 
-## Custom Configuration
+## Custom configuration
 
 You can create a custom mutex with different timeout settings:
 
@@ -42,9 +38,9 @@ const result = await mutex.withLock('resource', async () => {
 });
 ```
 
-## Advanced Usage
+## Advanced usage
 
-### Manual Lock Management
+### Manual lock management
 
 Sometimes you need more control over when locks are acquired and
 released:
@@ -69,10 +65,9 @@ const locked = await isLocked('resource');
 console.log(`Resource is ${locked ? 'locked' : 'available'}`);
 ```
 
-### Cancelling Operations
+### Cancelling operations
 
-You can cancel a mutex operation if it takes too long or if you need
-to stop it for any reason:
+You can cancel a mutex operation using an AbortSignal:
 
 ```typescript
 import { withMutex } from 'commandkit/mutex';
@@ -96,11 +91,10 @@ try {
 }
 ```
 
-### Using External Storage
+### Using external storage
 
-By default, mutexes store lock information in memory. If you're
-running multiple servers, you'll want to use external storage like
-Redis:
+Mutexes store lock information in memory by default. For multi-server
+deployments, use external storage like Redis:
 
 ```typescript
 import { Mutex, MutexStorage } from 'commandkit/mutex';
@@ -129,33 +123,7 @@ const mutex = createMutex({
 });
 ```
 
-## Default Settings
+## Default settings
 
 - **Timeout**: 30 seconds (30000ms)
 - **Storage**: In-memory (works for single-server applications)
-
-## Common Use Cases
-
-- **Database Transactions**: Ensure only one operation can modify data
-  at a time
-- **File System Access**: Prevent multiple operations from writing to
-  the same file
-- **Configuration Updates**: Make sure configuration changes don't
-  conflict
-- **Cache Invalidation**: Control when cache is cleared to prevent
-  race conditions
-- **Resource Pool Management**: Manage access to limited resources
-
-## Tips for Beginners
-
-1. **Use `withMutex` When Possible**: It automatically handles
-   cleanup, so you don't forget to release locks
-2. **Set Reasonable Timeouts**: Don't make timeouts too short (might
-   fail unnecessarily) or too long (might hang forever)
-3. **Use Descriptive Names**: Give your resources meaningful names
-   like `user:123:profile` or `database:users`
-4. **Handle Errors**: Always handle cases where lock acquisition fails
-5. **Think About Deadlocks**: Be careful not to create situations
-   where two operations wait for each other
-6. **Consider Your Setup**: Use external storage if you have multiple
-   servers

apps/website/docs/guide/14-useful-utilities/03-semaphore.mdx

@@ -1,17 +1,13 @@
 ---
 title: Semaphore
-description:
-  Control concurrent access to limited resources with async semaphores
 ---
 
-# Semaphore
+A semaphore controls the number of operations that can access a
+resource concurrently. It maintains a set number of permits, allowing
+only that many operations to proceed simultaneously while others wait
+in queue.
 
-A semaphore is like a parking lot with a limited number of spaces. It
-allows a specific number of operations to happen at the same time, but
-no more. Perfect for controlling access to limited resources like
-database connections.
-
-## Basic Usage
+## Basic usage
 
 The easiest way to use a semaphore is with the `withPermit` function,
 which automatically handles getting and releasing permits:
@@ -26,7 +22,7 @@ const result = await withPermit('database-connection', async () => {
 });
 ```
 
-## Custom Configuration
+## Custom configuration
 
 You can create a semaphore with specific limits and timeout settings:
 
@@ -46,9 +42,9 @@ const result = await semaphore.withPermit(
 );
 ```
 
-## Advanced Usage
+## Advanced usage
 
-### Manual Permit Management
+### Manual permit management
 
 Sometimes you need more control over when permits are acquired and
 released:
@@ -77,10 +73,9 @@ const available = await getAvailablePermits('resource');
 console.log(`${available} permits available`);
 ```
 
-### Cancelling Operations
+### Cancelling operations
 
-You can cancel a semaphore operation if it takes too long or if you
-need to stop it for any reason:
+You can cancel a semaphore operation using an AbortSignal:
 
 ```typescript
 import { withPermit } from 'commandkit/semaphore';
@@ -104,7 +99,7 @@ try {
 }
 ```
 
-### Monitoring Semaphore State
+### Monitoring semaphore state
 
 You can check how many permits are being used and how many are
 available:
@@ -123,11 +118,10 @@ console.log(
 );
 ```
 
-### Using External Storage
+### Using external storage
 
-By default, semaphores store permit information in memory. If you're
-running multiple servers, you'll want to use external storage like
-Redis:
+Semaphores store permit information in memory by default. For
+multi-server deployments, use external storage like Redis:
 
 ```typescript
 import { Semaphore, SemaphoreStorage } from 'commandkit/semaphore';
@@ -158,37 +152,8 @@ const semaphore = createSemaphore({
 });
 ```
 
-## Default Settings
+## Default settings
 
 - **Permits**: 1 (sequential access)
 - **Timeout**: 30 seconds (30000ms)
 - **Storage**: In-memory (works for single-server applications)
-
-## Common Use Cases
-
-- **Database Connection Pooling**: Limit how many database connections
-  are used at once
-- **API Rate Limiting with Concurrency**: Allow multiple API calls but
-  not too many
-- **File Upload Throttling**: Control how many files can be uploaded
-  simultaneously
-- **External Service Access**: Limit calls to third-party services
-- **Resource Pool Management**: Manage access to limited resources
-  like memory or CPU
-
-## Tips for Beginners
-
-1. **Use `withPermit` When Possible**: It automatically handles
-   cleanup, so you don't forget to release permits
-2. **Set Appropriate Limits**: Don't set too many permits (might
-   overwhelm resources) or too few (might be too slow)
-3. **Monitor Usage**: Keep an eye on how many permits are being used
-   to optimize performance
-4. **Use Descriptive Names**: Give your resources meaningful names
-   like `database:main` or `api:external`
-5. **Handle Errors**: Always handle cases where permit acquisition
-   fails
-6. **Consider Your Resources**: Set permit limits based on what your
-   system can actually handle
-7. **Think About Your Setup**: Use external storage if you have
-   multiple servers