docs: rebrand site and write all guide content

.gitignore

@@ -1 +1,2 @@
 __pycache__/
+.idea/

.nvmrc

@@ -0,0 +1 @@
+22

docs.json

@@ -1,21 +1,45 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "mint",
-  "name": "Trace Finance Developer Docs",
+  "theme": "palm",
+  "name": "Trace Finance",
   "colors": {
     "primary": "#15803D",
-    "light": "#07C983",
-    "dark": "#15803D"
+    "light": "#18E299",
+    "dark": "#0C8C5E"
   },
   "favicon": "/favicon.svg",
   "logo": {
     "light": "/logo/light.svg",
-    "dark": "/logo/dark.svg"
+    "dark": "/logo/dark.svg",
+    "href": "https://tracefinance.io"
+  },
+  "appearance": {
+    "default": "dark"
+  },
+  "background": {
+    "decoration": "gradient"
+  },
+  "fonts": {
+    "heading": {
+      "family": "Inter",
+      "weight": 600
+    },
+    "body": {
+      "family": "Inter",
+      "weight": 400
+    }
+  },
+  "styling": {
+    "eyebrows": "breadcrumbs",
+    "codeblocks": {
+      "theme": "tokyo-night"
+    }
   },
   "navigation": {
     "tabs": [
       {
         "tab": "Guides",
+        "icon": "book-open",
         "groups": [
           {
             "group": "Getting started",
@@ -32,7 +56,9 @@
               "guides/principles/versioning",
               "guides/principles/idempotency",
               "guides/principles/pagination",
+              "guides/principles/filtering",
               "guides/principles/money",
+              "guides/principles/datetime",
               "guides/principles/errors"
             ]
           },
@@ -45,13 +71,6 @@
               "journeys/withdrawal",
               "journeys/swap"
             ]
-          },
-          {
-            "group": "Webhooks",
-            "pages": [
-              "webhooks/overview",
-              "webhooks/events"
-            ]
           }
         ]
       }
@@ -72,7 +91,12 @@
         "label": "Support",
         "href": "mailto:support@tracefinance.io"
       }
-    ]
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Get started",
+      "href": "/quickstart"
+    }
   },
   "api": {
     "baseUrl": [
@@ -83,7 +107,12 @@
       "method": "bearer"
     }
   },
-  "description": "API documentation for Trace Finance's multi-currency account and payment platform.",
+  "description": "Explore guides, examples, and API references to build with Trace Finance.",
+  "variables": {
+    "sandboxUrl": "https://faas.sandbox.tracefinance.io",
+    "productionUrl": "https://faas.tracefinance.io",
+    "authUrl": "https://auth.tracefinance.io"
+  },
   "seo": {
     "indexing": "navigable"
   },

guides/authentication.mdx

@@ -1,7 +1,66 @@
 ---
 title: "Authentication"
-description: "Obtain and use Auth0 JWT tokens to authenticate requests to the Trace FX API."
+description: "Obtain and use JWT tokens to authenticate requests to the Trace FX API."
 sidebarTitle: "Authentication"
 ---
 
-{/* TODO: Write auth guide — Auth0 flow, obtaining tokens, X-Customer-Id claim, token rotation */}
+## Overview
+
+Every request to the Trace FX API must include a valid JSON Web Token (JWT) in the `Authorization` header.
+
+During onboarding you receive a **client ID** and **client secret**. Use these to obtain an access token from the Trace authentication service.
+
+## Details
+
+### Obtaining a token
+
+Request an access token from the token endpoint:
+
+```bash
+curl --request POST \
+  --url {{authUrl}}/api/oauth/client/token \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "clientId": "YOUR_CLIENT_ID",
+    "clientSecret": "YOUR_CLIENT_SECRET"
+  }'
+```
+
+A successful response includes the token and its lifetime:
+
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
+  "tokenType": "Bearer",
+  "expiresIn": 3600
+}
+```
+
+### Using the token
+
+Include the token in the `Authorization` header of every request:
+
+```bash
+curl --request GET \
+  --url {{sandboxUrl}}/api/accounts \
+  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
+```
+
+The token contains your customer identity — no separate customer ID header is needed.
+
+### Token lifecycle
+
+Tokens are valid for **1 hour** (3,600 seconds). Follow these best practices:
+
+1. **Store securely** — keep the token in memory after obtaining it.
+2. **Check before use** — inspect the `exp` claim in the JWT payload to confirm it has not expired.
+3. **Rotate proactively** — request a new token before the current one expires rather than waiting for a `401` response.
+
+<Warning>
+  Do not request a new token for every API call. Reuse tokens until they expire.
+</Warning>
+
+## Related
+
+- [Environments](/guides/environments) — sandbox and production base URLs
+- [Quickstart](/quickstart) — make your first API call

guides/environments.mdx

@@ -3,4 +3,41 @@ title: "Environments"
 description: "Sandbox and production base URLs, and what differs between them."
 ---
 
-{/* TODO: Write environments guide — sandbox vs production URLs, what resets, rate limits */}
+## Overview
+
+Trace FX provides two environments. Use sandbox for development and testing, and production for live integrations.
+
+| Environment | Base URL |
+| --- | --- |
+| Sandbox | `{{sandboxUrl}}` |
+| Production | `{{productionUrl}}` |
+
+## Details
+
+### Sandbox
+
+The sandbox is an isolated environment that replicates production behavior with test data. Use it to build and validate your integration before going live.
+
+- No real money is moved.
+- Test credentials are provided during onboarding.
+- Data may be reset periodically.
+
+### Production
+
+The production environment processes real transactions and serves live users. Access is granted after your integration has been validated in sandbox.
+
+- All operations affect real accounts and funds.
+- Subject to full compliance and security requirements.
+
+### Rate limits
+
+API requests are subject to rate limits in both environments. See [Errors](/guides/principles/errors) for status codes and retry guidance.
+
+### Availability
+
+The platform maintains **99.8% uptime** with the exception of scheduled maintenance or unforeseeable events. Scheduled maintenance is communicated at least **21 business days** in advance through official channels.
+
+## Related
+
+- [Authentication](/guides/authentication) — how to obtain tokens for each environment
+- [Quickstart](/quickstart) — make your first sandbox API call

guides/principles/datetime.mdx

@@ -0,0 +1,46 @@
+---
+title: "Date and time"
+description: "How dates and timestamps are formatted in the API."
+---
+
+## Overview
+
+All dates and timestamps in the Trace FX API use **UTC** in ISO 8601 format. No other timezones are accepted or returned.
+
+## How it works
+
+### Format
+
+```text
+yyyy-MM-ddTHH:mm:ss.SSSZ
+```
+
+Example: `2025-01-15T14:30:00.000Z`
+
+| Component | Description | Example |
+| --- | --- | --- |
+| `yyyy` | Four-digit year | `2025` |
+| `MM` | Two-digit month (01–12) | `01` |
+| `dd` | Two-digit day (01–31) | `15` |
+| `T` | Date/time separator | `T` |
+| `HH` | Hours in 24-hour format (00–23) | `14` |
+| `mm` | Minutes (00–59) | `30` |
+| `ss` | Seconds (00–59) | `00` |
+| `.SSS` | Milliseconds (optional) | `.000` |
+| `Z` | UTC timezone indicator | `Z` |
+
+## Examples
+
+A resource creation timestamp:
+
+```json
+{
+  "createdAt": "2025-01-15T14:30:00.000Z"
+}
+```
+
+Filtering by date range:
+
+```bash
+?filters=and(createdAt[gte]=2025-01-01T00:00:00.000Z,createdAt[lte]=2025-01-31T23:59:59.999Z)
+```

guides/principles/errors.mdx

@@ -3,4 +3,89 @@ title: "Errors"
 description: "How errors are structured and how to handle them."
 ---
 
-{/* TODO: Write errors guide — ErrorResponse shape (code, message, details), HTTP status codes, retry guidance */}
+## Overview
+
+The Trace FX API uses standard HTTP status codes and returns structured error responses. Every response includes an `X-Request-Id` header you can reference when contacting support.
+
+## How it works
+
+### Error response structure
+
+All errors follow the same shape:
+
+```json
+{
+  "code": "INVALID_DATA",
+  "message": "The field 'amount.value' must be a positive integer.",
+  "details": {}
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `code` | string | Machine-readable error code for programmatic handling |
+| `message` | string | Human-readable description of what went wrong |
+| `details` | object | Additional context (may be empty) |
+
+### HTTP status codes
+
+| Code | Meaning | When it happens |
+| --- | --- | --- |
+| `200` | OK | Request succeeded |
+| `201` | Created | Resource was created |
+| `204` | No content | Request succeeded with no response body |
+| `400` | Bad request | Invalid or malformed request data |
+| `401` | Unauthorized | Missing or invalid authentication token |
+| `404` | Not found | Resource does not exist |
+| `408` | Request timeout | Request took too long to process |
+| `409` | Conflict | Idempotency key conflict or state conflict |
+| `422` | Unprocessable entity | Valid syntax but business rule violation |
+| `429` | Too many requests | Rate limit exceeded |
+| `500` | Internal server error | Unexpected server failure |
+
+### Common error codes
+
+| Code | HTTP status | Description |
+| --- | --- | --- |
+| `INVALID_DATA` | 400 | Request body failed validation |
+| `RESOURCE_NOT_FOUND` | 404 | The requested resource does not exist |
+| `IDEMPOTENT_ID_CONFLICT` | 409 | Idempotency key was already used |
+| `INVALID_STATUS_CHANGE` | 422 | The resource cannot transition to the requested state |
+| `MFA_NOT_ENABLED` | 422 | Multi-factor authentication is required but not configured |
+
+### Retry guidance
+
+| Status code | Should retry? | Strategy |
+| --- | --- | --- |
+| `400`, `401`, `404`, `422` | No | Fix the request before retrying |
+| `408`, `429` | Yes | Back off and retry after the indicated period |
+| `409` | Depends | Check if the original request succeeded |
+| `500` | Yes | Retry with exponential backoff |
+
+<Tip>
+  Include the `X-Request-Id` from the response when opening a support ticket. This helps the team trace your request through the system.
+</Tip>
+
+## Examples
+
+A validation error:
+
+```json
+{
+  "code": "INVALID_DATA",
+  "message": "The field 'amount.value' must be a positive integer.",
+  "details": {
+    "field": "amount.value"
+  }
+}
+```
+
+A resource not found:
+
+```json
+{
+  "code": "RESOURCE_NOT_FOUND",
+  "message": "Account with id 'abc-123' was not found.",
+  "details": {}
+}
+```