[Portal] Nebula documentation update (#6201)

CORE-0000

<!-- start pr-codex -->

---

## PR-Codex overview
This PR enhances the documentation for `thirdweb Nebula`, adding metadata for various pages, improving FAQs, and introducing new sections on context filters, sessions, and response handling. It also updates the sidebar and integrates new features for better user guidance.

### Detailed summary
- Added `metadata` exports for multiple pages.
- Expanded FAQs with links for further information.
- Introduced sections on `Chat & Execute endpoints`, `Execute Configuration`, and `Sessions`.
- Updated sidebar to include new key concepts.
- Enhanced response handling documentation, including streaming and non-streaming responses.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

Author: saminacodes

apps/portal/src/app/nebula/api-reference/chat/page.mdx

@@ -2,7 +2,7 @@ import { EndpointMetadata } from './EndpointMetadata';
 
 <EndpointMetadata />
 
-#### Chat Actions
+## Chat Actions
 
 Chat actions represent blockchain transactions or operations that Nebula has prepared in response to your request. The response includes both a detailed explanation in the `message` field and the actual transaction data in the `actions` array.
 
@@ -113,4 +113,4 @@ const response = await fetch('https://nebula-api.thirdweb.com/chat', {
 
 const data = await response.json();
 const result = await handleNebulaResponse(data);
-```
+```

apps/portal/src/app/nebula/api-reference/page.mdx

@@ -1,3 +1,15 @@
+import { createMetadata } from "@doc";
+
+export const metadata = createMetadata({
+	image: {
+		title: "API Reference",
+		icon: "nebula",
+	},
+	title: "thirdweb Nebula API Reference",
+	description:
+		"Explore the thirdweb Nebula API reference to unlock the most powerful AI to interact with the blockchain and start building AI powered web3 apps.",
+});
+
 # Nebula API Reference
 
 Nebula provides a conversational interface to interact with blockchain data and services, and access to thirdweb tools.
@@ -13,7 +25,9 @@ https://nebula-api.thirdweb.com
 
 ## Authentication
 
-All API endpoints require authentication using the thirdweb secret key. Include this key in your request headers:
+All API endpoints require authentication using the thirdweb secret key. [Learn how to obtain a secret key.](/nebula/get-started).
+
+Include this key in your request headers:
 
 ```bash
 x-secret-key: YOUR_THIRDWEB_SECRET_KEY
@@ -31,161 +45,7 @@ curl -X POST https://nebula-api.thirdweb.com/chat \
   }'
 ```
 
-## Sessions
-
-Sessions maintain conversation threads with the AI and can be:
-
-- Created explicitly via the `/session` endpoint
-- Created automatically when sending a message without a session_id
-- Reused to maintain context across multiple messages
-- Configured with specific execution parameters
-
-Sessions persist your conversation history and custom configurations for blockchain data and thirdweb tools interactions.
-
-## Context Filters
-
-Control what blockchain data informs AI responses through context filtering:
-
-```json
-{
-  "context": {
-    "chain_ids": ["1"], // comma delimited list of chain ID's
-    "wallet_address": "0x..." // wallet address
-  }
-}
-```
-
-Benefits:
-- Filter by blockchain networks using chain IDs
-- Target specific contract addresses
-- Target specific wallet addresses
-- Control context scope for relevant responses
-- Optimize token usage and response relevance
-
-## Execute Configuration
-
-Configure transaction execution behavior using the execute config:
-
-```json
-{
-  "execute_config": {
-    "mode": "client",
-    "signer_wallet_address": "0x..."
-  }
-}
-```
-
-Parameters:
-- `mode`: Execution mode (currently supports "client")
-- `signer_wallet_address`: Wallet address for transaction signing
-
-When mode is "client", Nebula returns an unsigned transaction for local wallet signing.
-
-## Response Handling
-
-Nebula API supports two types of response modes: streaming and non-streaming. The mode is controlled by the `stream` parameter in your request.
-
-### Non-Streaming Responses
-
-When `stream: false`, the API returns a single JSON response:
-
-```json
-{
-  "result": {
-    "message": "The last 5 blocks on polygon are...",
-    "session_id": "abc",
-    "message_id": "1234"
-  }
-}
-```
-
-### Streaming Responses
-
-When `stream: true`, the API uses Server-Sent Events (SSE) to stream the response. You'll need to handle the following event types:
-
-1. `init`: Initializes the stream and provides session information
-2. `presence`: Provides backend status updates about worker processing
-3. `action`: Contains blockchain transaction or action data
-4. `delta`: Contains chunks of the response message text
-5. `error`: Contains error information if something goes wrong
-
-**Example SSE Stream:**
-```tsx
-event: init
-data: {
-  "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a",
-  "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164",
-  "type": "init",
-  "source": "user",
-  "data": ""
-}
-
-event: presence
-data: {
-  "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a",
-  "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164",
-  "type": "presence",
-  "source": "executor",
-  "data": "Performing function execution: ExecuteNativeTransferClientSigning"
-}
-
-event: action
-data: {
-  "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a",
-  "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164",
-  "type": "sign_transaction",
-  "source": "executor",
-  "data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}"
-}
-
-event: delta
-data: {"v": "To send 0.0001 ETH on the Sepolia network"}
-
-event: delta
-data: {"v": " to the address associated with"}
-```
-
-**JavaScript Example for Handling Streams:**
-```javascript
-const eventSource = new EventSource('/chat', {
-  headers: {
-    'x-secret-key': 'YOUR_THIRDWEB_SECRET_KEY'
-  }
-});
 
-let messageText = '';
-
-eventSource.addEventListener('init', (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Stream initialized:', data);
-});
-
-eventSource.addEventListener('presence', (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Backend status:', data.data);
-});
-
-eventSource.addEventListener('action', (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Received action:', data);
-  if (data.type === 'sign_transaction') {
-    // Handle transaction signing
-    handleTransaction(data);
-  }
-});
-
-eventSource.addEventListener('delta', (event) => {
-  const data = JSON.parse(event.data);
-  messageText += data.v;
-  console.log('Current message:', messageText);
-});
-
-eventSource.addEventListener('error', (event) => {
-  const error = JSON.parse(event.data);
-  console.error('Error:', error);
-  eventSource.close();
-});
-```
 
 
 

apps/portal/src/app/nebula/assets/streamed-response.png

@@ -10,7 +10,7 @@ Nebula supports the read and write context of any verified contract or any contr
 If you have a published contract you would like to enable for deployment through Nebula, please [contact us](https://thirdweb.com/contact-us). 
 
 ### Does Nebula have memory from past conversations?
-Nebula retains memory within the confines of a session.
+Nebula retains memory within the confines of a session. [Learn more about sessions](/nebula/key-concepts/sessions).
 
 ### What is the context size of Nebula?
 The context size or window is 128k tokens.

apps/portal/src/app/nebula/faqs/page.mdx

@@ -1,7 +1,18 @@
-import { Step, Steps, DocImage, Callout } from "@doc";
+import { Step, Steps, DocImage, Callout, createMetadata } from "@doc";
 import NewProject from "../assets/new-project.png";
 import KeysSetup from "../assets/keys.png";
 
+export const metadata = createMetadata({
+	image: {
+		title: "Get Started",
+		icon: "nebula",
+	},
+	title: "Get started with thirdweb Nebula: Set up Guide",
+	description:
+		"How to start building web3 capable apps with thirdweb Nebula, the most powerful AI to interact with the blockchain.",
+});
+
+
 # Get Started
 
 Learn how to get set up and started with the Nebula API to successfully prepare and enable a connected user to sign a transfer .

apps/portal/src/app/nebula/get-started/page.mdx

@@ -0,0 +1,5 @@
+# Chat & Execute endpoints
+
+The `/chat` endpoint is used for **natural language interactions** with the AI. It allows users to ask questions, get explanations, or retrieve blockchain-related insights, and execute transactions.
+
+The `/execute` endpoint is used for **triggering actual blockchain transactions** through AI-generated execution logic. This endpoint **performs actions** on-chain and is designed to be used without historical context. 

apps/portal/src/app/nebula/key-concepts/chat-execute/page.mdx

@@ -0,0 +1,24 @@
+# Context Filters
+
+Context filters help control what blockchain data the AI uses to generate responses. 
+
+You can specify:
+
+- Chain IDs – Choose which blockchain networks to pull data from.
+- Wallet Address – Focus on a specific wallet’s transactions, balances, and interactions.
+
+Benefits: 
+
+- **More relevant answers:** AI focuses only on the data you care about.
+- **Enable Scope**: Keep results relevant to networks and wallets specified.
+
+Example,
+
+```jsx
+{
+  "context": {
+    "chain_ids": ["1"],  // Ethereum network
+    "wallet_address": "0x123...abc"  // Specific wallet to analyze
+  }
+}
+```

apps/portal/src/app/nebula/key-concepts/context-filters/page.mdx

@@ -0,0 +1,19 @@
+# Execute Configuration
+
+Configure transaction execution behavior using the execute config:
+
+```json
+{
+  "execute_config": {
+    "mode": "client",
+    "signer_wallet_address": "0x..."
+  }
+}
+```
+
+Parameters:
+
+- `mode`: Execution mode (currently supports "client")
+- `signer_wallet_address`: Wallet address for transaction signing
+
+When mode is "client", Nebula returns an unsigned transaction for local wallet signing.