fix: another pass, todos

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

@@ -5,7 +5,7 @@ icon: "sitemap"
 sidebarTitle: "Architecture"
 ---
 
-Honcho is a memory infrastructure that continuously [*reasons*](/v2/documentation/core-concepts/reasoning) about data to build rich representations of peers (users, agents, or any entity) over time. This document explains the data model, system components, and how data flows through Honcho.
+Honcho is memory infrastructure that continuously [*reasons*](/v2/documentation/core-concepts/reasoning) about data to build rich representations of peers (users, agents, or any entity) over time. This document explains the data model, system components, and how data flows through Honcho.
 
 ## Data Model
 
@@ -95,7 +95,7 @@ Honcho is designed to be flexible. Settings cascade hierarchically from workspac
 
 ## Design Principles
 
-Honcho's architecture follows a few core principles. Everything revolves around building representations of peers (peer-centric). Memory isn't just storage--it's continuous inference (reasoning-first). Expensive operations happen in the background so they don't block user interactions (async by default). The system works with any LLM provider (provider-agnostic) and is built for isolation and scalability from the ground up (multi-tenant). Users and agents are both represented as peers, which enables flexible scenarios you couldn't easily model with a traditional user-assistant paradigm (unified paradigm).
+Honcho's architecture follows a few core principles. Everything revolves around building representations of peers (peer-centric). Memory isn't just storage--it's continual learning (reasoning-first). Expensive operations happen in the background so they don't block user interactions (async by default). The system works with any LLM provider (provider-agnostic) and is built for isolation and scalability from the ground up (multi-tenant). Users and agents are both represented as peers, which enables flexible scenarios you couldn't easily model with a traditional user-assistant paradigm (unified paradigm).
 
 ## Next Steps
 

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

@@ -18,7 +18,7 @@ Traditional RAG systems treat memory as static storage--they retrieve what was e
 
 Honcho uses formal logic to power its system because we believe you need reasoning to access insights that are only accessible by *rigorously thinking* about your data. Static retrieval can't surface implicit connections, struggles when new information contradicts old data, and fails when you need to make predictions under uncertainty.
 
-Formal logic reasoning is AI-native--it performs the rigorous, compute-intensive type of reasoning that humans struggle with, instantly and consistently. Honcho uses this capability to generate new insights that go beyond simple recall, transforming retrieved context into something richer and more useful.
+Formal logical reasoning is AI-native--it performs the rigorous, compute-intensive type of reasoning that humans struggle with, instantly and consistently. Honcho uses this capability to generate new insights that go beyond simple recall, transforming retrieved context into something richer and more useful.
 
 ## Formal Logic Framework
 
@@ -26,7 +26,7 @@ Honcho's memory system is powered by custom models trained to perform three type
 
 Why formal logic specifically? LLMs are uniquely well-suited for this reasoning task--it's well-represented in the pretraining data. LLMs can maintain consistent reasoning across thousands of observations without cognitive fatigue or belief resistance--which is extremely hard for humans to do reliably. The outputs are also composable, meaning logical conclusions can be stored, retrieved, and combined programmatically for dynamic context assembly.
 
-Here's an example of the data structure the reasoning models generate:
+Here's an example of a data structure the reasoning models generate:
 
 ```json
 {
@@ -54,7 +54,7 @@ Here's an example of the data structure the reasoning models generate:
 }
 ```
 
-The reasoning models output their "thinking" followed by things that were explicitly stated, which serve as premises to scaffold deductive conclusions. It's on top of this reasoning foundation that further reasoning is scaffolded. Currently that includes peer cards (key biographical information about the peer), duplicate checking (identifying redundant or contradictory information), induction (pattern recognition across multiple messages), and abduction (inferring the simplest explanations for observed behavior).
+The explicit reasoning model ([Neuromancer XR](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR)) outputs its "thinking" followed by things that were explicitly stated, which serve as premises to scaffold deductive conclusions. It's on top of this reasoning foundation that further reasoning is scaffolded. Currently that includes peer cards (key biographical information about the peer), consolidation (identifying redundant or contradictory information), induction (pattern recognition across multiple messages), and abduction (inferring the simplest explanations for observed behavior).
 
 The reasoning that Honcho does is something we're constantly iterating and improving on. Our goal is simple--provide the richest, most relevant context in the fastest, cheapest way possible in order to simulate statefulness in whatever setting you need.
 
@@ -62,7 +62,7 @@ The reasoning that Honcho does is something we're constantly iterating and impro
 
 When you write messages to Honcho, they're stored immediately and enqueued for background processing. Reasoning is computationally expensive, so processing asynchronously ensures fast writes while still providing rich reasoning capabilities. Messages are stored immediately without blocking, and session-based queues maintain chronological consistency so reasoning tasks affecting the same peer representation are always processed in order.
 
-The reasoning models extract explicit premises from message content, draw deductive conclusions from those premises, and use those conclusions to generate higher-order reasoning. These artifacts--observations, conclusions, summaries, peer cards--are stored as part of peer representations and indexed in vector collections for retrieval.
+The reasoning models extract explicit premises from message content, draw deductive conclusions from those premises, and use those conclusions to scaffold higher-order reasoning. These artifacts--observations, conclusions, summaries, peer cards--are stored as part of peer representations and indexed in vector collections for retrieval.
 
 ![Diagram for reasoning in Honcho](/images/reasoning.png)
 
@@ -70,14 +70,14 @@ The diagram above shows how agents write messages to Honcho, which triggers reas
 
 ## Balances & Design Choices
 
-Off-the-shelf LLMs can perform reasoning, but they aren't optimized for it. Honcho uses custom models trained specifically for structured output (consistent JSON schema with premises and conclusions), logical rigor (following formal reasoning rules rather than plausible-sounding text), and efficiency (smaller, faster models tuned for this specific task). This allows Honcho to reason more reliably and at lower cost than general-purpose frontier LLMs.
+Off-the-shelf LLMs can perform reasoning, but they aren't optimized for it. Honcho uses custom models trained specifically for logical rigor (following formal reasoning rules rather than plausible-sounding text), structured output (consistent JSON schema with premises and conclusions), and efficiency (smaller, faster models tuned for this specific task). This allows Honcho to reason more reliably and at lower cost than general-purpose frontier LLMs.
 
 The approach balances quality with practical constraints. Custom models are smaller and cheaper to run, background processing means reasoning doesn't block user interactions, and structured conclusions are more token-efficient than raw conversation history. Not every message requires full reasoning--we batch where appropriate to optimize update frequency.
 
-Honcho's reasoning capabilities are actively being improved. Current areas of development include enhanced inductive and abductive reasoning, multi-hop reasoning, and temporal reasoning. The system is designed to be extensible--new reasoning capabilities can be added without breaking existing functionality.
+Honcho's reasoning capabilities are actively being improved. Current areas of development include enhanced inductive and abductive reasoning, multi-hop  and temporal reasoning, and expanded file types and modalities. The system is designed to be extensible--new reasoning capabilities can be added without breaking existing functionality.
 
 <Note>
-If you find that the data you're uploading to Honcho isn't being reasoned over to your liking, we'd love to improve it for you and get your data ingested for free--reach out via [Discord](https://discord.gg/plasticlabs) or [email](mailto:support@plasticlabs.ai)!
+If you find that the data you're uploading to Honcho isn't being reasoned over to your liking, we'd love to improve it for you and ingest your data for free--reach out via [Discord](https://discord.gg/plasticlabs) or [email](mailto:support@plasticlabs.ai)!
 </Note>
 
 ## Next Steps

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

@@ -12,7 +12,7 @@ When you write messages to Honcho, the reasoning models extract premises, draw c
 
 A peer representation is made up of several types of artifacts that Honcho generates through [*reasoning*](/v2/documentation/core-concepts/reasoning):
 
-**Conclusions** are insights derived through formal logic. Deductive conclusions are things Honcho can be certain about based on the premises. Inductive conclusions identify patterns across multiple messages. Abductive conclusions infer the simplest explanations for observed behavior. For example, if a user frequently mentions work deadlines and rarely mentions hobbies, Honcho might inductively conclude they're time-constrained or career-focused.
+**Conclusions** are insights derived through formal logic. Deductive conclusions are things Honcho can be certain about based on extracted premises. Inductive conclusions identify patterns across multiple messages. Abductive conclusions infer the simplest explanations for observed behavior. For example, if a user frequently mentions work deadlines and rarely mentions hobbies, Honcho might inductively conclude they're time-constrained or career-focused.
 
 **Summaries** capture the essence of sessions. Short summaries are generated every 20 messages by default, and long summaries every 60 messages. These help compress conversation history into dense, queryable context.
 

docs/v2/documentation/features/advanced/overview.mdx

@@ -5,7 +5,7 @@ description: "Advanced configuration and monitoring options for Honcho"
 sidebarTitle: "Overview"
 ---
 
-Advanced features give you fine-grained control over Honcho's behavior and let you monitor system performance.
+Advanced features give you fine-grained control over Honcho's behavior and implementation.
 
 ## Configuration & Monitoring
 

docs/v2/documentation/features/advanced/queue-status.mdx

@@ -4,9 +4,9 @@ description: Learn how to check the status of Honcho's reasoning
 icon: "lines-leaning"
 ---
 
-Whenever `Messages` are stored in Honcho, a background process kicks off to [reason](/docs/v2/documentation/core-concepts/architecture#reasoning-layer) about the conversation and generate insights.
+Whenever messages are stored in Honcho, a background process kicks off to [reason](/v2/documentation/core-concepts/reasoning) about the conversation and generate insights.
 
-Reasoning is an asynchronous process and, depending on load may not immediately
+Reasoning is an asynchronous process and, depending on load, may not immediately
 generate insights for the latest message you've sent. To help with this, Honcho
 provides several utilities to check the status of the queue.
 
@@ -61,18 +61,18 @@ Promise<{
 ```
 </CodeGroup>
 
-Whenever a `Message` is sent it will generate several tasks. These could
+Whenever a message is sent it will generate several tasks. These could
 be tasks such as generating insights, cleaning up a representation, summarizing
 a conversation etc. These tasks are defined based on who is sending the
-message, what `Session` the message is in, and potentially who is observing the
+message, what session the message is in, and potentially who is observing the
 message. We call the combination of these parameters a `work_unit`
 
 This has a few different implications.
 
 - tasks within the same work_unit are processed sequentially, but multiple
 work_units will be processed in parallel
-- If local representations are turned in a Session then a `Message` will
-  generate an additional work unit for every `Peer` that has `observe_others=True`
+- If local representations are turned in a Session then a message will
+  generate an additional work unit for every peer that has `observe_others=True`
 
 The `get_queue_status` and `poll_queue_status` methods can take additional
 parameters to scope the status to a specific work unit
@@ -102,7 +102,7 @@ export const QueueStatusOptionsSchema = z.object({
 </CodeGroup>
 
 Additionally, there are queue status and polling queue status methods
-available on the `Session` objects in each of the SDKs.
+available on the session objects in each of the SDKs.
 
 Below are the function signatures for the session level queue status method
 

docs/v2/documentation/features/advanced/representation-scopes.mdx

@@ -4,7 +4,9 @@ description: 'Reasoning is on—control whose perspective it runs from'
 icon: 'circle'
 ---
 
-Once reasoning is enabled (see [Toggle Reasoning](/v2/documentation/features/advanced/toggle-reasoning)), you control **whose perspective** it runs from and **who gets observed**. This page covers:
+TODO: re-work, local and global aren't a thing anymore
+
+Once reasoning is enabled (see [Toggle Reasoning](/v2/documentation/features/advanced/toggle-reasoning)), you control whose perspective it runs from and who gets observed. This page covers:
 
 1. **Scoping** — global vs local representations
 2. **Configuration** — the `observe_me` and `observe_others` flags

docs/v2/documentation/features/chat.mdx

@@ -5,11 +5,11 @@ sidebarTitle: "Chat Endpoint"
 icon: "message-question"
 ---
 
-The Chat endpoint (`peer.chat()`) is the natural language interface to Honcho's reasoning. Instead of manually retrieving observations or conclusions, your LLM can ask questions and get synthesized answers based on all the reasoning Honcho has done about a peer. Think of it as agent-to-agent communication.
+The Chat endpoint (`peer.chat()`) is the natural language interface to Honcho's reasoning. Instead of manually retrieving conclusions, your LLM can ask questions and get synthesized answers based on all the reasoning Honcho has done about a peer. Think of it as agent-to-agent communication.
 
 ## Basic Usage
 
-The simplest way to use the Dialectic endpoint is to ask a question and get a text response:
+The simplest way to use the chat endpoint is to ask a question and get a text response:
 
 <CodeGroup>
 ```python Python
@@ -41,7 +41,7 @@ console.log(answer);
 ```
 </CodeGroup>
 
-The Dialectic endpoint searches through the peer's representation--all the conclusions Honcho has reasoned about them--and synthesizes a natural language answer.
+The chat endpoint searches through the peer's representation--all the conclusions Honcho has reasoned about them--and synthesizes a natural language answer.
 
 ## Streaming Responses
 
@@ -112,7 +112,7 @@ Respond appropriately based on the context.
 
 ### Conditional Logic
 
-Use Dialectic responses to drive application logic:
+Use chat endpoint responses to drive application logic:
 
 <CodeGroup>
 ```python Python
@@ -167,12 +167,14 @@ const goals = await peer.chat("What are the user's main goals or objectives?");
 
 When you call `peer.chat(query)`:
 
-1. Honcho searches through the peer's representation - conclusions drawn from reasoning over their messages
+TODO: update with agentic approach?
+
+1. Honcho searches through the peer's representation--conclusions drawn from reasoning over their messages
 2. Retrieves conclusions semantically relevant to your query
 3. Synthesizes them into a coherent natural language answer
 4. Returns the answer to your application
 
-The *deriver* runs continuously in the background, reasoning over new messages and updating representations. The Dialectic endpoint always has access to Honcho's latest conclusions about the peer.
+Honcho [reasoning](/v2/documentation/core-concepts/reasoning) runs continuously in the background, processing new messages and updating representations. The chat endpoint always has access to Honcho's latest conclusions about the peer.
 
 ## Best Practices
 
@@ -180,12 +182,12 @@ The *deriver* runs continuously in the background, reasoning over new messages a
 Instead of "Tell me about the user", ask "What communication style does the user prefer?" You'll get more actionable answers.
 
 ### Let your LLM formulate queries
-The Dialectic endpoint shines when your LLM decides what it needs to know. This creates dynamic, context-aware personalization.
+The chat endpoint shines when your LLM decides what it needs to know. This creates dynamic, context-aware personalization.
 
 ### Use for runtime decisions
-Don't just use Dialectic for LLM prompts - use it to drive application logic, routing, and feature flags based on user behavior.
+Don't just use chat for LLM prompts - use it to drive application logic, routing, and feature flags based on user behavior.
 
 ### Combine with get_context()
 Use `get_context()` for conversation context and `peer.chat()` for specific insights. They complement each other.
 
-For more ideas on using the Dialectic endpoint, see our blog post on [flexible agent communication](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API#how-it-works).
+For more ideas on using the chat endpoint, see our blog post on [flexible agent communication](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-chat-API#how-it-works).

docs/v2/documentation/features/get-context.mdx

@@ -6,6 +6,8 @@ icon: 'messages'
 
 The `get_context()` method is a powerful feature that retrieves formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others. This guide covers everything you need to know about working with session context.
 
+TODO: if reasoning is on by default (which we're changing the package to do), doesn't this mean that a working rep gets assembled?
+
 By default, the context includes a blend of summary and messages which covers the entire history of the session. Summaries are automatically generated at intervals and recent messages are included depending on how many tokens the context is intended to be. You can specify any token limit you want, and can disable summaries to fill that limit entirely with recent messages.
 
 ## Basic Usage
@@ -95,7 +97,7 @@ context = session.get_context(summary=False, tokens=2000)
 
 ### Peer Representation in Context
 
-You can include a peer's representation and peer card in the context by specifying `peer_target`. This is useful for providing the LLM with knowledge about a specific peer.
+You can include a peer's [representation](/v2/documentation/core-concepts/representation) and peer card in the context by specifying `peer_target`. This is useful for providing the LLM with knowledge about a specific peer.
 
 <CodeGroup>
 ```python Python
@@ -141,7 +143,9 @@ context = session.get_context(
 
 ### Semantic Search with Last Message
 
-Use `last_user_message` to fetch semantically relevant observations based on the most recent message:
+Use `last_user_message` to fetch semantically relevant conclusions based on the most recent message:
+
+TODO: Update code here
 
 <CodeGroup>
 ```python Python

docs/v2/documentation/introduction/overview.mdx

@@ -38,12 +38,27 @@ All the while usage dwindles, customers churn, and motivation to solve the probl
 
 Honcho has four storage primitives that work together:
 
+```mermaid
+ graph LR
+      W[Workspaces] -->|have| P[Peers]
+      W -->|have| S[Sessions]
+
+      S -->|have| SM[Messages]
+
+      P <-.->|many-to-many| S
+
+      style W fill:#B6DBFF,stroke:#333,color:#000
+      style P fill:#B6DBFF,stroke:#333,color:#000
+      style S fill:#B6DBFF,stroke:#333,color:#000
+      style SM fill:#B6DBFF,stroke:#333,color:#000
+```
+
 - **Workspaces** - Top-level containers that isolate different applications or environments
 - **Peers** - Any entity that persists over time (users, agents, objects, and more)
 - **Sessions** - Interaction threads between peers with temporal boundaries
 - **Messages** - Units of interaction that trigger reasoning
 
-When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical [*reasoning*](/v2/documentation/core-concepts/reasoning) to generate insights about each peer. These conclusions are stored as [*representations*](/v2/documentation/core-concepts/representation) that you can query to provide rich context for your agents.
+When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical [*reasoning*](/v2/documentation/core-concepts/reasoning) to generate conclusions about each peer. These conclusions are stored as [*representations*](/v2/documentation/core-concepts/representation) that you can query to provide rich context for your agents.
 
 ![Honcho Architecture](/images/architecture.png)
 

docs/v2/documentation/introduction/quickstart.mdx

@@ -4,9 +4,11 @@ icon: "bolt"
 sidebarTitle: "Quickstart"
 ---
 
-Let's start with a simple implementation.
+Let's get started with Honcho. In this quickstart, you will:
 
-TODO: move "next Steps" up here to "tell em what you're gonna tell em"
+- Set up a workspace with peers (user and assistant)
+- Ingest messages from across multiple sessions
+- Query the reasoning Honcho produces to get synthesized insights about the user
 
 <Note>
 Running the code below requires an API key. Create and account and get your API key at [app.honcho.dev](https://app.honcho.dev) under "API KEYS".