platform docs w/ new ui screenshots (#195)

* updated platform page

* fix: update explore page screenshots

* fix: empty object to init client

* fix: add async operations to ts code

* add: output structure for sessionContext, messages, and workingrep in docs

* Delete docs/scratch.md

* fix: review comments

* fix: delete the 212 version from changelog

docs/changelog/compatibility-guide.mdx

@@ -29,28 +29,7 @@ This guide helps you understand which versions of Honcho's API are compatible wi
   </Card>
 </CardGroup>
 
-### Honcho API v2.1.2
 
-<CardGroup cols={2}>
-  <Card title="TypeScript SDK" icon="js">
-    **Compatible Version:** v1.4.0
-
-    Install with:
-    ```bash
-    npm install @honcho-ai/sdk@1.4.0
-    ```
-  </Card>
-
-  <Card title="Python SDK" icon="python">
-    **Compatible Version:** v1.4.0
-
-    Install with:
-    ```bash
-    pip install honcho-ai==1.4.0
-    ```
-  </Card>
-
-</CardGroup>
 
 ## Version Compatibility Table
 
@@ -58,7 +37,6 @@ This guide helps you understand which versions of Honcho's API are compatible wi
 |-------------------|---------------|------------|
 | v2.3.0 (Current) | v1.4.0 | v1.4.0 |
 | v2.2.0 | v1.3.0 | v1.3.0 |
-| v2.1.2 | v1.2.1 | v1.2.2 |
 | v2.1.1 | v1.2.1 | v1.2.2 |
 | v2.1.0 | v1.2.1 | v1.2.2 |
 | v2.0.5 | v1.1.0 | v1.1.0 |

docs/v2/documentation/core-concepts/architecture.mdx

@@ -234,7 +234,7 @@ Think of Dialectic Chat as an assisting agent that your main agent can consult f
   <Card title="API Reference" icon="play" href="/v2/api-reference/introduction">
     Detailed API documentation and examples
   </Card>
-  <Card title="Quick Start" icon="rocket" href="/v2/documentation/introduction/quickstart">
+  <Card title="Quickstart" icon="rocket" href="/v2/documentation/introduction/quickstart">
     Get started with your first integration
   </Card>
 </CardGroup>

docs/v2/documentation/introduction/overview.mdx

@@ -86,7 +86,7 @@ Example Queries
 
 Ready to integrate Honcho into your application?
 
-<CardGroup cols={2}> <Card title="Quick Start Guide" icon="rocket"
+<CardGroup cols={2}> <Card title="Quickstart Guide" icon="rocket"
 href="/v2/documentation/introduction/quickstart"> Get up and running with
 Honcho in minutes </Card> <Card title="Core Concepts" icon="brain"
 href="/v2/documentation/core-concepts/glossary"> Understand Honcho's

docs/v2/documentation/introduction/quickstart.mdx

@@ -19,9 +19,13 @@ For production-level use, Honcho offers two powerful ways to leverage ambient pe
 
 Have your project use Honcho's ambient personalization capabilities in just a few steps. No signup required!
 
-<Note>
-This quickstart uses the demo server at https://demo.honcho.dev
-</Note>
+<Info>
+By default, the SDK uses the demo server hosted at demo.honcho.dev. The demo server is meant for quick experimentation and the data is cleared on a regular basis. Do not use for production applications.
+
+For production use:
+1. Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys)
+2. Set `environment="production"` and provide your `api_key`
+</Info>
 
 ## 1. Install the SDK
 
@@ -49,19 +53,63 @@ pnpm add @honcho-ai/sdk
 
 ## 2. Initialize the Client
 
+The Honcho client is the main entry point for interacting with Honcho's API. By default, it uses the demo environment and a default workspace.
+
+### Demo Environment (Default)
+
 <CodeGroup>
 ```python Python
 from honcho import Honcho
 
-# Initialize client (using the demo environment)
+# Initialize client (uses demo environment and default workspace)
 client = Honcho()
+
+# Demo environment: create your own workspace using a nanoid or uuid
+# otherwise it could be difficult to retrieve your message data via API
+client = Honcho(
+    workspace="your-workspace-id"
+)
 ```
 
 ```typescript TypeScript
 import { Honcho } from '@honcho-ai/sdk';
 
-// Initialize client (using the demo environment)
-const client = new Honcho();
+// Initialize client (uses demo environment)
+const client = new Honcho({});
+
+// Demo environment: create your own workspace using a nanoid or uuid
+// otherwise it could be difficult to retrieve your data via API
+const client = new Honcho({
+    workspace: "your-workspace-id"
+})
+```
+</CodeGroup>
+
+### Production Environment
+
+<CodeGroup>
+```python Python
+from honcho import Honcho
+
+# Production environment with API key
+client = Honcho(
+    api_key="your-api-key",
+    environment="production",
+    # Create a workspace, otherwise set to "default"
+    # workspace="your-workspace-id"
+)
+```
+
+```typescript TypeScript
+import { Honcho } from '@honcho-ai/sdk';
+
+// Production environment with API key
+const client = new Honcho({
+    apiKey: "your-api-key",
+    environment: "production",
+    // Create a workspace, otherwise set to "default"
+    // workspace: "your-workspace-id"
+});
 ```
 </CodeGroup>
 
@@ -76,8 +124,8 @@ bob = client.peer("bob")
 ```
 
 ```typescript TypeScript
-const alice = client.peer("alice")
-const bob = client.peer("bob")
+const alice = await client.peer("alice")
+const bob = await client.peer("bob")
 ```
 </CodeGroup>
 
@@ -92,8 +140,8 @@ session.add_peers([alice, bob])
 ```
 
 ```typescript TypeScript
-const session = client.session("session_1")
-session.addPeers([alice, bob])
+const session = await client.session("session_1")
+await session.addPeers([alice, bob])
 ```
 </CodeGroup>
 
@@ -114,7 +162,7 @@ session.add_messages([
 ```
 
 ```typescript TypeScript
-session.addMessages([
+await session.addMessages([
     alice.message("Hi Bob, how are you?"),
     bob.message("I'm good, thank you!"),
     alice.message("What are you doing today after work?"),

docs/v2/documentation/introduction/vibecoding.mdx

@@ -7,7 +7,7 @@ sidebarTitle: 'Vibecoding Setup'
 
 Get Honcho up and running in minutes using AI coding assistants. These prompts are specifically optimized for Cursor and Claude to generate production-ready code with minimal effort.
 
-## 🚀 Quick Start
+## 🚀 Quickstart
 
 Choose your path based on your use case:
 

docs/v2/documentation/reference/platform.mdx

@@ -16,7 +16,7 @@ and start building with Honcho.
 ## 1. Go to [app.honcho.dev](https://app.honcho.dev)
 
 Create an account to start using Honcho. If a teammate already uses Honcho, ask
-them to invite you to their organization; otherwise, you’ll see a banner
+them to invite you to their organization; otherwise, you'll see a banner
 prompting you to create a new one.
 
 <Frame>
@@ -24,87 +24,99 @@ prompting you to create a new one.
 </Frame>
 
 Once you've created an organization, you'll be taken to the dashboard and see
-the welcome page.
+the **Get Started** page with integration guidance and links to documentation.
 
 <img src="/images/app-screenshots/get-started-copy.png" alt="Honcho Dashboard Getting Started"/>
 
 Each organization has dedicated infrastructure running to isolate your
 workloads. Until you activate a subscription under the
 [Billing](https://app.honcho.dev/billing) page, the infrastructure will be
-deactivated. You can check the status of your instance by going to the
-[Status](https://app.honcho.dev/status) page.
+deactivated.
 
-<img src="/images/app-screenshots/no-subscription-status.png" alt="Honcho Status Page with No Subscription" />
+## 2. Activate your Honcho instance
 
-## **2. Set up billing to activate your Honcho instance**
+Navigate to the [Billing](https://app.honcho.dev/billing) page to activate your subscription. Your Honcho instance provisions automatically, and you can monitor the deployment on the [Instance Status](https://app.honcho.dev/status) page until all systems show a green check mark.
 
-Once you activate your subscription, your Honcho instance provisions
-automatically, and you can watch the status page until all systems show a green
-check mark.
+<img src="/images/app-screenshots/status-page.png" alt="Instance Status Page" />
+
+You can also upgrade Honcho when new versions are made available directly from the status page.
+
+<img src="/images/app-screenshots/upgrade-honcho.png" alt="Upgrade Honcho" />
+
+The **Performance** page provides comprehensive monitoring with usage metrics, health analytics, API response times, and endpoint usage across Honcho.
 
 <img src="/images/app-screenshots/performance-analytics.png" alt="Performance Analytics Dashboard" />
 
-Here you can monitor your Honcho instance health, usage metrics, and
-performance analytics. See request volume, API response times, and endpoint
-usage across all your AI applications.
-
-You can also upgrade Honcho when new versions are made available.
-
-## **3. Manage API Keys**
-Create and manage API keys for different environments. You can create
-admin-level keys that have access to the entire Honcho instance or scope keys
-to restrict access to `Workspaces`, `Peers`, or `Sessions`.
+## 3. Manage API Keys
+The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to specific `Workspaces`, `Peers`, or `Sessions`.
 
 <img src="/images/app-screenshots/api-keys.png" alt="API Key Management Dashboard" />
 
-## **4. Test with API Playground**
-Use our Postman-like API playground to test queries, explore endpoints, and
-validate your integration. Send requests directly to your Honcho instance and
-see real-time responses with full request/response logging.
+## 4. Test with API Playground
+The [API Playground](https://app.honcho.dev/playground) provides a Postman-like interface to test queries, explore endpoints, and validate your integration. Send requests directly to your Honcho instance with real-time responses and full request/response logging.
 
 <img src="/images/app-screenshots/api-playground.png" alt="API Playground Interface" />
 
-## **5. Create a Workspace**
-On the explore page, you can see and interact with the data stored in your
-Honcho instance. You can create `Workspaces`, `Peers`, `Sessions`, and `Messages`.
+## 5. Workspaces
+The [Explore](https://app.honcho.dev/explore) page provides comprehensive `Workspace` management where you can create workspaces and begin exploring the platform. Each `Workspace` serves as a container for organizing your Honcho data.
 
-<img src="/images/app-screenshots/explore-honcho.png" alt="Explore Honcho Page" />
+<img src="/images/app-screenshots/explore-honcho.png" alt="Workspace Table" />
 
-## **6. Peers & Sessions Management**
-Click into a `Workspace` to open up the `Workspace` dashboard. Here you can create
-`Peers` and `Sessions`, use the Dialectic API and add `Messages` to your `Peer`
-representations. Utilize your ability to search across all `Messages` in a
-`Workspace`.
+Click into any workspace to access a general overview of `Peers` and `Sessions`. Here you can quickly create `Peers`, `Sessions`, and add multiple `Peers` to any particular `Session`. Edit the metadata and configuration for a `Workspace` with the Edit Config button. Click into any entity to navigate to their respective utilities pages or click the expand icon to view Workspace-wide `Peers` and `Sessions` data tables with more details.
 
 <img src="/images/app-screenshots/workspace-dash.png" alt="Workspace Dashboard Overview" />
 
+## 6. Peer Dashboard & Utilities
+Expand the `Peers` list from the `Workspace` dashboard to see a detailed view of `Peers`.
 
-## **7. Peer Utilities & Chat Endpoint**
-Select a `Peer` to open its utilities. From here you can search that `Peer`'s
-`Messages`, view participating `Sessions`, or edit its metadata.
+<img src="/images/app-screenshots/peer-dash.png" alt="Peer Dashboard" />
 
-The Chat Endpoint allows you to send a query through the Honcho API to get
-information about the `Peer`'s representation. If you include the `Session` ID,
-the query will be scoped to `Messages` and the representation of a `Peer`
-within that `Session`.
+Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Global Peer Configuration](/v2/documentation/core-concepts/configuration), and in the tabs below, explore all utilities for the `Peer`. 
+<img src="/images/app-screenshots/peer-utilities.png" alt="Peer Management Dashboard" />
 
-<Frame>
-<img src="/images/app-screenshots/peer-utilities.png" alt="Peer Utilities Dashboard" width="400" />
-</Frame>
+Utilities include:
+- **Message search** across all sessions for a particular peer
+- **Dialectic Chat** to query peer representations globally or session-scoped (results vary dependant on the peer's configuration)
+
+<img src="/images/app-screenshots/chat-endpoint.png" alt="Chat Endpoint" />
+
+- **Session logs** view which `Sessions` the `Peer` is active
+- **Peer configuration and metadata management** including [Session-Peer Configuration](/v2/documentation/core-concepts/configuration#session-peer-configuration)
 
 
-## **8. Session Dashboard & Get Context**
-From the workspace dashboard, navigate to a `Session` to find options to add `Peers`, view `Messages`, and search across all `Messages` for a particular session.
+<img src="/images/app-screenshots/peer-utilities.png" alt="Peer Management Dashboard" />
 
-Use the **Get Context** feature to quickly generate output that fits into your
-LLM’s context window. Get a subset of messages with an optional summary
-based on the token count you input. The [Session Context](../../guides/get-context) guide goes over how to use this in your agents
+## 7. Session Dashboard & Utilities
+Click into the sessions view within a workspace to see a table of all of your `Sessions` data.
 
-<img src="/images/app-screenshots/session-dash.png" alt="Session Dashboard Overview" />
+<img src="/images/app-screenshots/session-dash.png" alt="Sessions Table" />
 
-<Frame>
-<img src="/images/app-screenshots/create-message.png" alt="Create Message Interface" width="400" />
-</Frame>
+Click into a particular `Session` to open its utilities page.  
+
+<img src="/images/app-screenshots/session-utilities.png" alt="Session Utilities" />
+
+Here you can:
+- **View and Add Messages** within the `Session`, filter messages by `Peer`
+- **Advanced search** across `Session` messages
+- **Peer management** for adding and removing `Peers` and editing a `Peer`'s Session-level configuration
+- **Get Context** feature for generating LLM-ready context with customizable token limits
+
+<img src="/images/app-screenshots/get-context.png" alt="Get Context" />
+
+
+
+
+
+
+## 8. Webhook Integration
+The [Webhooks](https://app.honcho.dev/webhooks) page enables Webhook creation and management.
+<img src="/images/app-screenshots/webhooks-page.png" alt="Webhooks Dashboard" />
+
+## 9. Organization Member Access
+The [Members](https://app.honcho.dev/members) page provides organization administration to manage your team's access to Honcho with the ability to grant admin permissions.
+
+
+<img src="/images/app-screenshots/members-dashboard.png" alt="Members Dashboard" />
 
 
 ## Go Further

docs/v2/documentation/reference/sdk.mdx

@@ -30,7 +30,13 @@ pnpm add @honcho-ai/sdk
 ```
 </CodeGroup>
 
-## Quick Start
+## Quickstart
+
+<Info>
+Without configuration, the SDK defaults to the demo server. For production use:
+1. Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys)
+2. Set `environment="production"` and provide your `api_key`
+</Info>
 
 <CodeGroup>
 ```python Python
@@ -67,11 +73,11 @@ import { Honcho } from "@honcho-ai/sdk";
 const honcho = new Honcho({});
 
 // Create peers
-const alice = honcho.peer("alice");
-const assistant = honcho.peer("assistant");
+const alice = await honcho.peer("alice");
+const assistant = await honcho.peer("assistant");
 
 // Create a session for conversation
-const session = honcho.session("conversation-1");
+const session = await honcho.session("conversation-1");
 
 // Add messages to conversation
 await session.addMessages([
@@ -204,10 +210,10 @@ workspaces = honcho.get_workspaces()
 
 ```typescript TypeScript
 // Get or create a peer
-const peer = honcho.peer(id);
+const peer = await honcho.peer(id);
 
 // Get or create a session
-const session = honcho.session(id);
+const session = await honcho.session(id);
 
 // List all peers in workspace (returns Page<Peer>)
 const peers = await honcho.getPeers();
@@ -275,9 +281,9 @@ alice.set_metadata(metadata)
 ```
 
 ```typescript TypeScript
-// Create peers (lazy creation - no API call yet)
-const alice = honcho.peer("alice");
-const assistant = honcho.peer("assistant");
+// Create peers (returns Promise<Peer>)
+const alice = await honcho.peer("alice");
+const assistant = await honcho.peer("assistant");
 
 // Peer properties
 console.log(`Peer ID: ${alice.id}`);
@@ -293,7 +299,7 @@ const sessionResponse = await alice.chat("What happened in session-1?", {
 const streamResponse = await alice.chat("Tell me a story", { stream: true });
 
 // Add content to a session with a peer
-const session = honcho.session("session-1");
+const session = await honcho.session("session-1");
 await session.addMessages([
   alice.message("I love TypeScript programming"),
   alice.message("Today I learned about async programming"),
@@ -368,8 +374,8 @@ metadata = session.get_metadata()
 ```
 
 ```typescript TypeScript
-// Create session (like peers, lazy creation)
-const session = honcho.session("conversation-1");
+// Create session (returns Promise<Session>)
+const session = await honcho.session("conversation-1");
 
 // Session properties
 console.log(`Session ID: ${session.id}`);
@@ -466,6 +472,32 @@ const anthropicMessages = context.toAnthropic(assistant);
 ```
 </CodeGroup>
 
+The SessionContext object has the following structure:
+
+```json
+{
+  "id": "string",
+  "messages": [
+    {
+      "id": "string",
+      "content": "string",
+      "peer_id": "string",
+      "session_id": "string",
+      "workspace_id": "string",
+      "metadata": {},
+      "created_at": "2024-01-15T10:30:00Z",
+      "token_count": 42
+    }
+  ],
+  "summary": {
+    "content": "string",
+    "message_id": 123,
+    "summary_type": "short|long",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
 ## Advanced Usage
 
 ### Multi-Party Conversations
@@ -494,11 +526,13 @@ moderator_view = moderator.chat("What feedback am I getting?", session_id=group_
 
 ```typescript TypeScript
 // Create multiple peers
-const users = Array.from({ length: 5 }, (_, i) => honcho.peer(`user-${i}`));
-const moderator = honcho.peer("moderator");
+const users = await Promise.all(
+  Array.from({ length: 5 }, (_, i) => honcho.peer(`user-${i}`))
+);
+const moderator = await honcho.peer("moderator");
 
 // Create group session
-const groupChat = honcho.session("group-discussion");
+const groupChat = await honcho.session("group-discussion");
 await groupChat.addPeers([...users, moderator]);
 
 // Add messages from different peers
@@ -681,12 +715,12 @@ support_agent = honcho.peer(f"agent-{agent_id}")
 
 ```typescript TypeScript
 // Peers and sessions are lightweight - create as needed
-const alice = honcho.peer("alice");
-const session = honcho.session("chat-1");
+const alice = await honcho.peer("alice");
+const session = await honcho.session("chat-1");
 
 // Use descriptive IDs for better debugging
-const userSession = honcho.session(`user-${userId}-support-${ticketId}`);
-const supportAgent = honcho.peer(`agent-${agentId}`);
+const userSession = await honcho.session(`user-${userId}-support-${ticketId}`);
+const supportAgent = await honcho.peer(`agent-${agentId}`);
 ```
 </CodeGroup>
 
@@ -706,7 +740,9 @@ context = session.get_context(tokens=1500)  # Limit context size
 
 ```typescript TypeScript
 // Lazy creation - no API calls until needed
-const peers = Array.from({ length: 100 }, (_, i) => honcho.peer(`user-${i}`)); // Fast
+const peers = await Promise.all(
+  Array.from({ length: 100 }, (_, i) => honcho.peer(`user-${i}`))
+);
 
 // Batch operations when possible
 await session.addMessages(

docs/v2/guides/dialectic-endpoint.mdx

@@ -38,7 +38,7 @@ session = honcho.session("demo-session")
 import { Honcho } from '@honcho-ai/sdk';
 
 // use the default workspace
-const honcho = new Honcho();
+const honcho = new Honcho({});
 
 // get/create a peer
 const peer = await honcho.peer('demo-user');

docs/v2/guides/get-context.mdx

@@ -233,9 +233,9 @@ import { Honcho } from "@honcho-ai/sdk";
     const openai = new OpenAI();
 
     // Set up conversation
-    const session = honcho.session("support-chat");
-    const user = honcho.peer("user-123");
-    const assistant = honcho.peer("support-bot");
+    const session = await honcho.session("support-chat");
+    const user = await honcho.peer("user-123");
+    const assistant = await honcho.peer("support-bot");
 
     // Add conversation history
     await session.addMessages([

docs/v2/guides/overview.mdx

@@ -5,7 +5,7 @@ description: 'Helpful guides and design patterns for building with Honcho'
 icon: 'hat-wizard'
 ---
 
-<Note> Before you start a tutorial, follow [Quick Start](/v2/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. </Note>
+<Note> Before you start a tutorial, follow [Quickstart](/v2/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. </Note>
 
 AI development often feels like magic - you craft the right prompt and get exactly what you need. Our Spellbooks are practical guides that show you how to cast effective spells with Honcho.
 

docs/v2/guides/search.mdx

@@ -151,6 +151,25 @@ results = my_peer.search("budget planning", filters={"session_id": my_session.id
 ```
 </CodeGroup>
 
+The search results return an array of message objects with the following structure:
+
+```json
+{
+  "items": [
+    {
+      "id": "<string>",
+      "content": "<string>",
+      "peer_id": "<string>",
+      "session_id": "<string>",
+      "metadata": {},
+      "created_at": "2023-11-07T05:31:56Z",
+      "workspace_id": "<string>",
+      "token_count": 123
+    }
+  ]
+}
+```
+
 ### Filter results by time range
 
 <CodeGroup>

docs/v2/guides/streaming-response.mdx

@@ -50,7 +50,7 @@ import { Honcho } from '@honcho-ai/sdk';
 
 (async () => {
     // Initialize client (using the default workspace)
-    const honcho = new Honcho();
+    const honcho = new Honcho({});
 
     // Create or get peers
     const user = await honcho.peer('demo-user');
@@ -178,7 +178,7 @@ import { Honcho } from '@honcho-ai/sdk';
 (async () => {
     async function restaurantRecommendationChat() {
       // Initialize client
-      const honcho = new Honcho();
+      const honcho = new Honcho({});
 
       // Create peers
       const user = await honcho.peer('food-lover');

docs/v2/guides/working-rep.mdx

@@ -59,9 +59,9 @@ import { Honcho } from "@honcho-ai/sdk";
 const honcho = new Honcho({});
 
 // Create peers and session
-const user = honcho.peer("user-123");
-const assistant = honcho.peer("ai-assistant");
-const session = honcho.session("support-conversation");
+const user = await honcho.peer("user-123");
+const assistant = await honcho.peer("ai-assistant");
+const session = await honcho.session("support-conversation");
 
 // Add conversation to trigger representation generation
 await session.addMessages([
@@ -77,6 +77,7 @@ const response = await user.chat("What is this user's main concern right now?",
 // Retrieve the cached working representation for the user
 const userRepresentation = await session.workingRep("user-123");
 console.log("Cached user representation:", userRepresentation);
+// Returns: { representation: Object }
 ```
 </CodeGroup>