Prism Gateway docs rewrite - Phase 1 & 2

src/lib/navigation.ts

@@ -353,36 +353,87 @@ export const tabNavigation: NavTab[] = [
           {
             title: 'Concepts',
             items: [
-              { title: 'Core Concepts', href: '/docs/prism/concepts/core' },
-              { title: 'API Reference', href: '/docs/prism/concepts/api-reference' },
+              { title: 'How it works', href: '/docs/prism/concepts/core' },
+              { title: 'Virtual keys & access control', href: '/docs/prism/concepts/virtual-keys' },
               { title: 'Configuration', href: '/docs/prism/concepts/configuration' },
-              { title: 'Platform Integration', href: '/docs/prism/concepts/platform-integration' },
+              { title: 'Platform integration', href: '/docs/prism/concepts/platform-integration' },
             ]
           },
           {
             title: 'Features',
             items: [
-              { title: 'Manage Providers', href: '/docs/prism/features/providers' },
-              { title: 'Routing & Reliability', href: '/docs/prism/features/routing' },
-              { title: 'Guardrails', href: '/docs/prism/features/guardrails' },
-              { title: 'Caching', href: '/docs/prism/features/caching' },
-              { title: 'Cost Tracking & Budgets', href: '/docs/prism/features/cost-tracking' },
-              { title: 'Streaming', href: '/docs/prism/features/streaming' },
-              { title: 'Shadow Experiments', href: '/docs/prism/features/shadow-experiments' },
-              { title: 'Rate Limiting', href: '/docs/prism/features/rate-limiting' },
-              { title: 'MCP & A2A', href: '/docs/prism/features/mcp-a2a' },
-              { title: 'Simulation Using SDK', href: '/docs/simulation/features/simulation-using-sdk' },
-              { title: 'Evaluate Tool Calling', href: '/docs/simulation/features/evaluate-tool-calling' },
-              { title: 'Fix My Agent', href: '/docs/simulation/features/fix-my-agent' },
-              { title: 'Replay', href: '/docs/simulation/features/observe-to-simulate' },
-              { title: 'Voice Replay', href: '/docs/simulation/features/voice-replay' },
-              { title: 'Prompt Simulation', href: '/docs/simulation/features/prompt-simulation' },
+              {
+                title: 'Providers',
+                items: [
+                  { title: 'Supported providers', href: '/docs/prism/features/providers' },
+                  { title: 'Self-hosted models', href: '/docs/prism/features/self-hosted-models' },
+                ]
+              },
+              {
+                title: 'API Reference',
+                items: [
+                  { title: 'Endpoints overview', href: '/docs/prism/api/endpoints' },
+                  { title: 'Chat completions', href: '/docs/prism/api/chat' },
+                  { title: 'Embeddings & reranking', href: '/docs/prism/api/embeddings' },
+                  { title: 'Media endpoints', href: '/docs/prism/api/media' },
+                  { title: 'Assistants API', href: '/docs/prism/api/assistants' },
+                  { title: 'Files & vector stores', href: '/docs/prism/api/files' },
+                  { title: 'Async & batch', href: '/docs/prism/api/async-batch' },
+                  { title: 'Request & response headers', href: '/docs/prism/api/headers' },
+                ]
+              },
+              {
+                title: 'Routing',
+                items: [
+                  { title: 'Routing & reliability', href: '/docs/prism/features/routing' },
+                ]
+              },
+              {
+                title: 'Safety & Policy',
+                items: [
+                  { title: 'Guardrails', href: '/docs/prism/features/guardrails' },
+                ]
+              },
+              {
+                title: 'Performance',
+                items: [
+                  { title: 'Caching', href: '/docs/prism/features/caching' },
+                  { title: 'Rate limiting', href: '/docs/prism/features/rate-limiting' },
+                ]
+              },
+              {
+                title: 'Cost & Observability',
+                items: [
+                  { title: 'Cost tracking', href: '/docs/prism/features/cost-tracking' },
+                  { title: 'Observability', href: '/docs/prism/features/observability' },
+                  { title: 'Shadow experiments', href: '/docs/prism/features/shadow-experiments' },
+                ]
+              },
+              {
+                title: 'Agentic',
+                items: [
+                  { title: 'MCP & A2A', href: '/docs/prism/features/mcp-a2a' },
+                ]
+              },
+            ]
+          },
+          {
+            title: 'Admin',
+            items: [
+              { title: 'Organization management', href: '/docs/prism/admin/organizations' },
             ]
           },
           {
             title: 'Deployment',
             items: [
-              { title: 'Self-Hosted', href: '/docs/prism/deployment/self-hosted' },
+              { title: 'Self-hosted', href: '/docs/prism/deployment/self-hosted' },
+            ]
+          },
+          {
+            title: 'Guides',
+            items: [
+              { title: 'Error handling', href: '/docs/prism/guides/errors' },
+              { title: 'Troubleshooting', href: '/docs/prism/guides/troubleshooting' },
             ]
           },
         ]

src/pages/docs/prism/admin/organizations.mdx

@@ -0,0 +1,177 @@
+---
+title: "Organization management"
+description: "Manage organizations, members, and org-level settings in Prism."
+---
+
+## About
+
+Each Prism organization is an isolated environment with its own providers, routing rules, rate limits, budgets, and API keys. Organizations are the top-level unit for multi-tenancy in Prism.
+
+---
+
+## Organization settings
+
+Organization config controls all gateway behavior for that org. Settings are managed via the dashboard or the admin API.
+
+<Tabs items={["Dashboard", "Python (Prism SDK)", "TypeScript (Prism SDK)"]}>
+
+<Tab title="Dashboard">
+
+Go to **Settings > Organization** in the Future AGI dashboard. From here you can:
+
+- View and edit org-level configuration (providers, routing, caching, etc.)
+- Manage members and roles
+- View API key inventory
+- Set budgets and rate limits
+
+</Tab>
+
+<Tab title="Python (Prism SDK)">
+
+```python
+from prism import Prism
+
+# base_url = inference gateway, control_plane_url = admin/config API
+client = Prism(
+    api_key="sk-prism-your-key",
+    base_url="https://gateway.futureagi.com",
+    control_plane_url="https://api.futureagi.com",
+)
+
+# Get org config
+config = client.org_configs.retrieve(org_id="your-org-id")
+
+# Update org config
+client.org_configs.update(
+    org_id="your-org-id",
+    config={
+        "rate_limiting": {
+            "enabled": True,
+            "rpm": 1000,
+        },
+        "budgets": {
+            "limit": 500.00,
+            "period": "monthly",
+        },
+    },
+)
+```
+
+</Tab>
+
+<Tab title="TypeScript (Prism SDK)">
+
+```typescript
+import { Prism } from "@futureagi/prism";
+
+const client = new Prism({
+    apiKey: "sk-prism-your-key",
+    baseUrl: "https://gateway.futureagi.com",
+    controlPlaneUrl: "https://api.futureagi.com",
+});
+
+const config = await client.orgConfigs.retrieve({
+    orgId: "your-org-id",
+});
+
+await client.orgConfigs.update({
+    orgId: "your-org-id",
+    config: {
+        rate_limiting: {
+            enabled: true,
+            rpm: 1000,
+        },
+        budgets: {
+            limit: 500.0,
+            period: "monthly",
+        },
+    },
+});
+```
+
+</Tab>
+
+</Tabs>
+
+---
+
+## Members and roles
+
+Organizations can have multiple members with different roles.
+
+| Role | Permissions |
+|---|---|
+| **Owner** | Full access. Can delete the org, manage billing, and change all settings. |
+| **Admin** | Can manage providers, keys, routing, budgets, and members (except owner). |
+| **Member** | Can view config and create API keys. Cannot change org settings. |
+| **Viewer** | Read-only access to dashboard, logs, and analytics. |
+
+### Managing members
+
+Members are managed through the Future AGI dashboard at **Settings > Members**. Invite new members by email. Each member can belong to multiple organizations.
+
+---
+
+## API key management
+
+Each organization has its own pool of API keys (virtual keys). Keys inherit org-level settings and can have additional per-key restrictions.
+
+```python
+# List keys for an org
+keys = client.keys.list(org_id="your-org-id")
+for key in keys:
+    print(f"{key.name}: {key.key_prefix}...")
+
+# Create a new key
+new_key = client.keys.create(
+    org_id="your-org-id",
+    name="backend-service",
+    rate_limit_rpm=100,
+    allowed_models=["gpt-4o", "gpt-4o-mini"],
+)
+print(f"Key: {new_key.key}")  # full key shown only at creation
+
+# Revoke a key
+client.keys.delete(key_id=new_key.id)
+```
+
+See [Virtual keys & access control](/docs/prism/concepts/virtual-keys) for detailed key configuration (RBAC, IP ACL, model restrictions).
+
+---
+
+## Multi-tenancy patterns
+
+### One org per customer
+
+For SaaS products, create a separate org per customer. Each customer gets isolated providers, budgets, and rate limits:
+
+- Customer A: budget $100/month, access to gpt-4o-mini only
+- Customer B: budget $500/month, access to gpt-4o and claude-sonnet-4-6
+- Customer C: unlimited budget, all models
+
+### One org with per-key isolation
+
+For internal teams, use a single org with per-key restrictions:
+
+- Marketing team key: rate limit 50 RPM, budget $200/month
+- Engineering team key: rate limit 500 RPM, budget $1000/month
+- Data science key: rate limit 200 RPM, all models, no budget cap
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Virtual keys" href="/docs/prism/concepts/virtual-keys">
+    Per-key restrictions, RBAC, and IP ACL
+  </Card>
+  <Card title="Configuration" href="/docs/prism/concepts/configuration">
+    Configuration hierarchy and sections
+  </Card>
+  <Card title="Rate limiting & budgets" href="/docs/prism/features/rate-limiting">
+    Per-org and per-key rate limits
+  </Card>
+  <Card title="Cost tracking" href="/docs/prism/features/cost-tracking">
+    Cost attribution across teams
+  </Card>
+</CardGroup>