[Portal] Nebula documentation update (#6201)

CORE-0000

<!-- start pr-codex -->

---

## PR-Codex overview
This PR enhances the documentation for `thirdweb Nebula`, adding detailed metadata, explanations of new features, and clarifying existing concepts. It includes updates to various pages, improving user understanding of plugins, sessions, context filters, and response handling.

### Detailed summary
- Added `metadata` exports to multiple `.mdx` files.
- Enhanced FAQ entries with links and additional context.
- Updated `sidebar` to include new key concepts.
- Added sections on `Chat & Execute endpoints`, `Execute Configuration`, and `Context Filters`.
- Introduced new content on `Response Handling` and streaming vs non-streaming responses.
- Clarified `Sessions` management and benefits.
- Replaced `Stack` with `Grid` in the `page.mdx` and updated links.
- Improved descriptions and examples for API usage and configurations.

> ✨ 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.
 

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.