Improve docs for LLMs

docs/getting-started/account.md

@@ -13,3 +13,8 @@ You can create an account using your Github account by clicking the "Continue wi
 Alternatively you can create an account using your email address and password by clicking "Sign Up".
 
 If chosen to create an account using your email address, we will ask for your first name, last name and email. You'll then be asked to enter a password. Finally we will ask you to verify the email address you've provided. You should receive an email with a 6 digit code.
+
+## Reference Documentation
+
+For more details about accounts and the data model:
+* [Data Model](/docs/reference/data-model) - Complete overview of accounts, API tokens, audiences, and alerts

docs/getting-started/adding-funds.md

@@ -51,4 +51,10 @@ View all account activity on the [Billing](https://console.notifox.com/?view=bil
 
 ## Next Steps
 
-Now that you have funds, you're ready to [send your first alert](/docs/getting-started/alert)!
+Now that you have funds, you're ready to [send your first alert](/docs/getting-started/alert)!
+
+## Reference Documentation
+
+For more details about pricing and costs:
+* [SMS Parts Reference](/docs/reference/parts) - Understanding SMS parts, encoding, and cost calculation
+* [Data Model](/docs/reference/data-model) - Overview of accounts, balances, and billing

docs/getting-started/alert.md

@@ -8,23 +8,32 @@ Now that you have an account, API token, and verified audience, you're ready to
 
 ## What Are Alerts?
 
-Alerts are messages you send through the Notifox API. Notifox supports two channels:
+An **alert** is a message you send through the Notifox API to a specific audience via a chosen channel. 
 
-* **SMS** - Text messages sent to phone numbers
-* **Email** - Emails sent to email addresses
+**Alert Structure:**
+- **audience** (required): The audience identifier/slug (e.g., `"joe"`, `"oncall"`) - see [Creating an Audience](./audience.md)
+- **alert** (required): The message content (string)
+- **channel** (required): Either `"sms"` or `"email"` - the delivery method
+
+Notifox supports two channels:
+
+* **SMS** - Text messages sent to verified phone numbers
+* **Email** - Emails sent to verified email addresses
 
 They're perfect for:
 * Notifying yourself or your team about server issues
 * Sending critical system alerts
 * Getting notified about important events in your application
 
+For a complete overview of how alerts, audiences, channels, and other objects relate, see the [Data Model](/docs/reference/data-model) reference.
+
 ## Choosing a Channel
 
 When sending an alert, you can specify the `channel` parameter:
 
 | Channel | Cost | Max Length | Best For |
 |---------|------|------------|----------|
-| `sms` | $0.025/part | ~765 chars (5 parts) | Urgent, time-sensitive alerts |
+| `sms` | $0.025/part | 765 chars (5 parts) | Urgent, time-sensitive alerts |
 | `email` | $0.001/email | 50,000 chars | Detailed alerts, logs, reports |
 
 **Note:** The channel you choose must be configured for the audience. For example, if you want to send an email, the audience must have a verified email address.

docs/getting-started/api-token.md

@@ -4,7 +4,19 @@ sidebar_position: 2
 
 # Create an API token
 
-An API token (or sometimes referred to as API key) is used to authenticate with the Notifox API.
+An **API token** (also called API key) is a secret string used to authenticate all requests to the Notifox API.
+
+**Type:** String (secret credential)
+
+**Format:** Alphanumeric string, typically 40+ characters
+
+**Usage:** Include in the `Authorization: Bearer <token>` header for all API requests
+
+**Important:** 
+- API tokens are secrets: treat them like passwords
+- Each token is shown only once when created
+- You can create up to 10 API tokens per account
+- Tokens don't expire unless you delete them
 
 ## Creating an API token
 
@@ -57,4 +69,10 @@ Keep in mind that once you delete an API token, it can no longer be used. Any re
 * **Rotate tokens regularly**: Periodically delete old tokens and create new ones, especially if you suspect a token may have been compromised.
 * **Use different tokens for different environments**: Create separate tokens for production, staging, and development to better track usage and limit blast radius if one is compromised.
 * **Don't share tokens**: API tokens grant full access to send alerts from your account. Only share tokens with trusted team members who need API access.
-* **Delete unused tokens**: Remove tokens that are no longer in use to reduce your attack surface.
+* **Delete unused tokens**: Remove tokens that are no longer in use to reduce your attack surface.
+
+## Reference Documentation
+
+For more details about API tokens and authentication:
+* [Data Model](/docs/reference/data-model) - Overview of API tokens and other core objects
+* [Alerts API Reference](/docs/reference/alerts-api) - API authentication and error handling

docs/getting-started/audience.md

@@ -4,12 +4,19 @@ sidebar_position: 3
 
 # Create an Audience
 
-Audiences are how you tell Notifox who should receive your alerts. Think of an audience as a named contact—like "joe", "oncall" or "dev-team" that you can reference when sending alerts.
+An **audience** is a named identifier (slug) that maps to verified contact methods. Think of it as a label you create (like `"joe"`, `"oncall"`, or `"dev-team"`) that you reference when sending alerts through the API.
+
+**Important:** An audience is:
+- A **slug/identifier** (string) that you choose
+- **Not** a user ID, email address, or phone number
+- A way to reference verified contact methods in your API calls
 
 Each audience can have:
-* A **phone number** for SMS alerts
-* An **email address** for email alerts
-* Or both!
+* **At most one** verified phone number for SMS alerts (or none)
+* **At most one** verified email address for email alerts (or none)
+* Or both (one phone + one email)
+
+**Example:** If you create an audience named `"joe"` with a verified phone number and email, you can send alerts to `"joe"` via SMS or email by specifying the channel in your API request. An audience can also have just a phone number, just an email address, or both.
 
 Let's create your first audience together.
 
@@ -19,7 +26,7 @@ Head over to the [Audiences](https://console.notifox.com/?view=audiences) page a
 
 ![audience modal](./images/audience-1.png)
 
-You'll see a simple form asking for an audience name. Choose something descriptive that you'll remember—like `oncall`, `dev-team`, or `support`. The name can include letters, numbers, hyphens, and underscores, but no spaces.
+You'll see a simple form asking for an audience name. Choose something descriptive that you'll remember, like `oncall`, `dev-team`, or `support`. The name can include letters, numbers, hyphens, and underscores, but no spaces.
 
 Click **Create Audience** when you're ready. You'll automatically be taken to the detailed view for your new audience.
 
@@ -33,7 +40,7 @@ In the detailed view, you'll see a **Phone Number** section with an **Add** butt
 
 ![add phone modal](./images/audience-2.png)
 
-Enter your US phone number (it should start with `+1`). The form will help you format it correctly. You'll also see a brief message about SMS alerts—this is required for compliance.
+Enter your US phone number (it should start with `+1`). The form will help you format it correctly. You'll also see a brief message about SMS alerts: this is required for compliance.
 
 Click **Add Phone Number**. Notifox will automatically send a 6-digit verification code to that number via SMS.
 
@@ -63,7 +70,7 @@ Your audience is now ready to use. You'll see it listed on the [Audiences](https
 
 ![audiences list](./images/audience-4.png)
 
-You can click the edit icon (pencil) next to any audience to manage it—add or remove phone numbers and email addresses, or delete the audience entirely.
+You can click the edit icon (pencil) next to any audience to manage it: add or remove phone numbers and email addresses, or delete the audience entirely.
 
 ## Which channel to use?
 
@@ -74,4 +81,10 @@ You can click the edit icon (pencil) next to any audience to manage it—add or
 
 You can configure both channels on the same audience and choose which one to use when sending each alert.
 
-**What's next?** Now that you have an audience set up, you're ready to [add some funds](./adding-funds.md) and send your first alert!
+**What's next?** Now that you have an audience set up, you're ready to [add some funds](./adding-funds.md) and send your first alert!
+
+## Reference Documentation
+
+For more details about audiences and the data model:
+* [Data Model](/docs/reference/data-model) - Complete overview of audiences, alerts, channels, and how they relate
+* [Alerts API Reference](/docs/reference/alerts-api) - Full API documentation for sending alerts

docs/intro.md

@@ -20,31 +20,31 @@ But most notification platforms are built for marketing teams, not developers:
 
 * **Single-channel limitations**: Many services only support one channel (SMS or email), forcing you to use multiple providers for different use cases.
 
-* **Expensive and complex**: Traditional SMS providers require carrier verification, campaign registration, and number leasing—costing $18-24 before you send your first message.
+* **Expensive and complex**: Traditional SMS providers require carrier verification, campaign registration, and number leasing, costing $18-24 before you send your first message.
 
 * **Over-engineered**: You don't need marketing features, campaign management, or enterprise infrastructure for simple alerts to yourself and your team.
 
 You need a simple, affordable way to send notifications across multiple channels without jumping through enterprise hoops or paying for features you'll never use.
 
 ## What Notifox Is
 
-Notifox is a **developer-focused multi-channel notification platform** that lets you send alerts to verified recipients (yourself and teammates) with a single API call:
+Notifox is a **developer-focused multi-channel notification platform** that lets you send alerts to audiences (yourself and teammates) with a single API call:
 
 * **Multiple channels**: Send alerts via SMS ($0.025/part) for urgent notifications, or Email ($0.001/email) for detailed reports. Choose the right channel for each alert.
 
-* **No setup friction**: Since you're only sending to verified recipients, we handle all the complexity. No carrier verification, no number leasing, no campaigns.
+* **No setup friction**: Since you're only sending to verified audiences, we handle all the complexity. No carrier verification, no number leasing, no campaigns.
 
-* **Usage-based pricing**: Pay only for what you send—SMS at $0.025 per part, Email at $0.001 per email. No monthly fees, no minimums, no hidden costs.
+* **Usage-based pricing**: Pay only for what you send: SMS at $0.025 per part, Email at $0.001 per email. No monthly fees, no minimums, no hidden costs.
 
-* **Simple verification**: Add recipients by verifying phone numbers and email addresses. Up to 15 verified recipients per account.
+* **Simple verification**: Add recipients by verifying phone numbers and email addresses. Up to 15 audiences per account.
 
 * **Built for developers**: Designed specifically for sending critical notifications and alerts, not mass marketing campaigns.
 
 * **Easy channel switching**: The same API works for both channels. Switch between SMS and email with a single parameter change.
 
 ## What Notifox Isn't
 
-* **Not a mass marketing platform**: You can only send to verified recipients (up to 15). Not suitable for sending messages to customers, users, or unverified numbers.
+* **Not a mass marketing platform**: You can only send to up to 15 audiences. Not suitable for sending messages to customers, users, or unverified numbers.
 
 * **Not a replacement for Twilio**: If you need to send to unverified numbers, create marketing campaigns, or send thousands of messages, Twilio or AWS SNS are better fits.
 
@@ -108,3 +108,13 @@ curl -X POST https://api.notifox.com/alert \
 5. **Send your first alert** using the API, SDK, or interactive console
 
 Get started in minutes, not days. No carrier verification, no campaigns, no enterprise sales calls. Just simple, multi-channel notifications that work.
+
+## Reference Documentation
+
+For complete API and technical documentation:
+
+* **[Data Model](/docs/reference/data-model)** - Complete overview of accounts, API tokens, audiences, alerts, channels, and how they relate. Essential for understanding core concepts.
+* **[Alerts API Reference](/docs/reference/alerts-api)** - Complete API documentation: endpoints, request/response formats, error codes, rate limits, and examples.
+* **[SMS Parts Reference](/docs/reference/parts)** - Understanding SMS parts, encoding (GSM-7 vs UCS-2), character limits, and cost calculation.
+
+These reference pages provide detailed technical information for both humans and AI assistants.

docs/reference/alerts-api.md

@@ -26,7 +26,7 @@ The request body must be valid JSON containing:
 * `audience` (string, required)
   * The name of the audience to send the alert to
   * Must match a verified audience name in your account
-  * Case-insensitive
+  * Case-sensitive (e.g., `"joe"` and `"Joe"` are different audiences)
 * `alert` (string, required)
   * The message text you want to send
   * Cannot be empty
@@ -41,7 +41,7 @@ The request body must be valid JSON containing:
 | Feature | SMS | Email |
 |---------|-----|-------|
 | Cost | $0.025 per part | $0.001 per email |
-| Max length | ~765 chars (5 parts) | 50,000 characters |
+| Max length | 765 chars (5 parts) | 50,000 characters |
 | Rate limit | 5 per 5 minutes | 100 per 5 minutes |
 | Encoding | GSM-7 or UCS-2 | UTF-8 |
 | Prefix/Footer | "Notifox: " prefix | Footer disclaimer |
@@ -125,7 +125,8 @@ On success, you'll receive a `200 OK` response with a JSON body:
 **Part limits:**
 * **Single-part**: Up to 160 characters (GSM-7) or 70 characters (UCS-2)
 * **Multi-part**: 153 characters per additional part (GSM-7) or 67 characters (UCS-2)
-* **Total maximum**: ~765 characters (GSM-7) or ~335 characters (UCS-2)
+* **Total maximum**: Exactly 765 characters (GSM-7) or ~335 characters (UCS-2)
+  * For 5-part messages: 5 × 153 = 765 characters (all parts use 153 in multipart SMS)
 
 See [SMS Parts and Message Length](/docs/reference/parts) for detailed information.
 
@@ -192,7 +193,7 @@ If you exceed these limits, you'll receive a `429 Too Many Requests` response.
 |---------|-------|
 | `alert message cannot be empty` | The `alert` field is missing or empty |
 | `alert message cannot be empty or only whitespace` | Message contains only spaces/newlines (email) |
-| `alert message cannot be greater than 5000 characters` | SMS message exceeds 5000 chars |
+| `alert message cannot be greater than 765 characters` | SMS message exceeds 765 chars (5 parts maximum) |
 | `alert message cannot be greater than 50000 characters` | Email message exceeds 50,000 chars |
 | `alert message contains invalid UTF-8 encoding` | Email contains invalid UTF-8 characters |
 | `alert message cannot contain null bytes` | Email contains null (`\x00`) characters |
@@ -322,3 +323,7 @@ On success, you'll receive a `200 OK` response with a JSON body:
 | `400` | Bad Request | Invalid request format or empty alert |
 | `500` | Internal Server Error | Server-side error occurred |
 
+## Related Reference Documentation
+
+* [Data Model](/docs/reference/data-model) - Complete overview of alerts, audiences, channels, and how objects relate
+* [SMS Parts Reference](/docs/reference/parts) - Understanding SMS parts, encoding, character limits, and cost calculation