docs: fixing core language

README.md

@@ -226,7 +226,7 @@ For wiring the Honcho SDK into an existing application, install the integration
 npx skills add plastic-labs/honcho
 ```
 
-Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs `honcho-memory` — the runtime counterpart that teaches an already-connected agent how to *use* Honcho as memory (recall/record loop, session and peer strategy). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding).
+Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy) plus its path skills `honcho-mcp` and `honcho-cli` that teach an already-connected agent how to actually drive the tools. Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding).
 
 ### Other MCP clients
 

skills/honcho-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: honcho-integration
-description: Integrate Honcho memory and social cognition into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, implementing the dialectic chat endpoint for AI agents, or wiring Honcho into bot frameworks (nanobot, openclaw, picoclaw, etc).
+description: Integrate Honcho memory into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, and accessing Honcho's representation.
 allowed-tools: Read, Glob, Grep, Bash(uv:*), Bash(bun:*), Bash(npm:*), Edit, Write, WebFetch, AskUserQuestion
 ---
 
@@ -10,7 +10,7 @@ allowed-tools: Read, Glob, Grep, Bash(uv:*), Bash(bun:*), Bash(npm:*), Edit, Wri
 
 Honcho is an open source memory library for building stateful agents. It works with any model, framework, or architecture. You send Honcho the messages from your conversations, and custom reasoning models process them in the background — extracting premises, drawing conclusions, and building rich representations of each participant over time. Your agent can then query those representations on-demand ("What does this user care about?", "How technical is this person?") and get grounded, reasoned answers.
 
-The key mental model: **Peers** are any participant — human or AI. Both are represented the same way. Observation settings (`observe_me`, `observe_others`) control which peers Honcho reasons about. Typically you want Honcho to model your users (`observe_me=True`) but not your AI assistant (`observe_me=False`). **Sessions** scope conversations between peers. **Messages** are the raw data you feed in — Honcho reasons about them asynchronously and stores the results as the peer's **representation**. No messages means no reasoning means no memory.
+The key mental model: **Peers** are any participant — human or AI. Both are represented the same way. Observation settings (`observe_me`, `observe_others`) control which peers Honcho reasons about. Typically you want Honcho to model your users (`observe_me=True`) but not anything with deterministic behavior (`observe_me=False`). **Sessions** scope conversations between peers. **Messages** are the raw data you feed in — Honcho reasons about them asynchronously and stores the results as the peer's **representation**. No messages means no reasoning means no memory.
 
 Your agent accesses this memory through `peer.chat(query)` (ask a natural language question, get a reasoned answer — a few seconds of live reasoning) or `session.context()` (near-instant read of formatted history + representation). Prefer `context()` for per-turn grounding; use `chat()` when you need a reasoned answer.
 
@@ -104,7 +104,7 @@ Based on interview responses, implement the integration:
 - If the Honcho CLI is available, run `honcho doctor` to confirm connectivity before testing the integration code
 - Use `honcho peer list` and `honcho peer chat` to verify peers exist and the dialectic endpoint works independently of the integration
 - Ensure all message exchanges are stored to Honcho
-- Verify AI peers have `observe_me=False` (unless user specifically wants AI observation)
+- Verify deterministic bot peers have `observe_me=False`; AI-assistant peers can keep observation on (it's fine to model them)
 - Check that the workspace ID is consistent across the codebase
 - Confirm environment variable for API key is documented
 
@@ -118,7 +118,7 @@ Based on interview responses, implement the integration:
 
 2. **Get an API key** ask the user to get a Honcho API key from <https://app.honcho.dev> and add it to the environment.
 
-3. **Verify with the CLI** (optional but recommended). If the user has the Honcho CLI installed (`pip install honcho-cli`), they can validate their setup before writing any integration code:
+3. **Verify with the CLI** (optional but recommended). If the user has the Honcho CLI installed (`uv install honcho-cli`), they can validate their setup before writing any integration code:
 
    ```bash
    honcho init          # persist API key + URL to ~/.honcho/config.json
@@ -152,7 +152,7 @@ When integrating Honcho into an existing codebase:
 - [ ] Set up `HONCHO_API_KEY` environment variable
 - [ ] Initialize Honcho client with a single workspace ID
 - [ ] Create peers for all entities (users AND AI assistants)
-- [ ] Set `observe_me=False` for AI peers
+- [ ] Set `observe_me=False` for deterministic bot peers (optional for AI assistants — fine to leave observation on)
 - [ ] Configure sessions with appropriate peer observation settings
 - [ ] Choose integration pattern:
   - [ ] Tool call pattern for agentic systems
@@ -166,7 +166,7 @@ When integrating Honcho into an existing codebase:
 
 1. **Multiple workspaces**: Use ONE workspace per application
 2. **Forgetting AI peers**: Create peers for AI assistants, not just users
-3. **Observing AI peers**: Set `observe_me=False` for AI peers unless you specifically want Honcho to model your AI's behavior
+3. **Modeling bots**: Set `observe_me=False` for deterministic bots (scripted output — nothing meaningful to model). For AI assistants it's fine to leave observation on; turning it off is an optional optimization when you only care about the user.
 4. **Not storing messages**: Always call `add_messages()` to feed Honcho's reasoning engine
 5. **Blocking on processing**: Messages are processed asynchronously — don't poll or wait for reasoning to complete before continuing
 

skills/honcho-integration/references/agent-patterns.md

@@ -2,13 +2,13 @@
 
 How your AI accesses Honcho's user context. Pick based on the interview answer to Question Set 2. These build on the client/peer/session setup in `core-patterns.md`.
 
-- **Pattern A — Dialectic chat as a tool call** (recommended for agents): the agent decides when to query context on-demand.
+- **Pattern A — Dialectic chat as a tool call**: the agent decides when to query context on-demand.
 - **Pattern B — Pre-fetch with targeted queries**: fetch a fixed set of attributes before each LLM call.
 - **Pattern C — `context()` for LLM integration**: inject conversation history + representation into the prompt.
 
 > **Speed note.** `chat()` runs live dialectic reasoning (a few seconds) — Patterns A and B call it. `context()` (Pattern C) is a near-instant read. Prefer `context()` for per-turn grounding; reach for `chat()` when you genuinely need a reasoned answer.
 
-## Pattern A: Dialectic Chat as a Tool Call (Recommended for Agents)
+## Pattern A: Dialectic Chat as a Tool Call
 
 Make Honcho's chat endpoint available as a **tool** for your AI agent. This lets the agent query user context on-demand.
 
@@ -152,7 +152,7 @@ async function getUserContextForPrompt(userId: string): Promise<Record<string, s
 
 ## Pattern C: Get Context for LLM Integration
 
-Use `context()` for conversation history with built-in LLM formatting. This is a near-instant read — no dialectic reasoning — so it's the cheapest way to ground each turn.
+Use `context()` for conversation history with built-in LLM formatting. This is a near-instant read so it's the cheapest way to ground each turn.
 
 **Python:**
 
@@ -161,7 +161,7 @@ import openai
 
 session = honcho.session("conversation-123")
 user = honcho.peer("user-123")
-assistant = honcho.peer("assistant", configuration=PeerConfig(observe_me=False))
+assistant = honcho.peer("assistant")
 
 # Get context formatted for your LLM
 context = session.context(
@@ -198,7 +198,7 @@ import OpenAI from 'openai';
 
 const session = await honcho.session("conversation-123");
 const user = await honcho.peer("user-123");
-const assistant = await honcho.peer("assistant", { configuration: { observeMe: false } });
+const assistant = await honcho.peer("assistant");
 
 // Get context formatted for your LLM
 const context = await session.context({

skills/honcho-integration/references/bot-frameworks.md

@@ -127,7 +127,7 @@ Key patterns (shared):
 
 - IDs sanitized to `^[a-zA-Z0-9_-]+` (Honcho requirement)
 - User peer: `observe_me=True, observe_others=True`
-- Assistant peer: `observe_me=False, observe_others=True`
+- Assistant/bot peer: `observe_others=True`; set `observe_me=False` only for deterministic bots (scripted output — nothing to model). AI-assistant bots can keep `observe_me=True`.
 
 If references exist for this framework, use them directly from `{baseDir}/references/bot-frameworks/<framework>/`.
 

skills/honcho-integration/references/bot-frameworks/nanobot/session.py

@@ -137,7 +137,10 @@ class HonchoSessionManager:
 
         session = self.honcho.session(session_id)
 
-        # Configure peer observation settings
+        # Configure peer observation settings.
+        # observe_me=False on the assistant skips modeling it — optional for an
+        # AI assistant (fine to leave observation on); it's really only needed
+        # for deterministic bots, where there's nothing meaningful to model.
         from honcho.api_types import SessionPeerConfig
         user_config = SessionPeerConfig(observe_me=True, observe_others=True)
         ai_config = SessionPeerConfig(observe_me=False, observe_others=True)

skills/honcho-integration/references/core-patterns.md

@@ -70,23 +70,31 @@ Create peers for **every entity** in your business logic - users AND AI assistan
 ```python
 from honcho.api_types import PeerConfig
 
-# Human users
+# Human users (observed by default)
 user = honcho.peer("user-123")
 
-# AI assistants - set observe_me=False so Honcho doesn't model the AI
-assistant = honcho.peer("assistant", configuration=PeerConfig(observe_me=False))
-support_bot = honcho.peer("support-bot", configuration=PeerConfig(observe_me=False))
+# AI assistants can be observed too — leave observe_me on (the default) if you
+# want a model of the assistant.
+assistant = honcho.peer("assistant")
+
+# Deterministic bots (scripted/rule-based) - set observe_me=False; there's
+# nothing meaningful for Honcho to model.
+notification_bot = honcho.peer("notification-bot", configuration=PeerConfig(observe_me=False))
 ```
 
 **TypeScript:**
 
 ```typescript
-// Human users
+// Human users (observed by default)
 const user = await honcho.peer("user-123");
 
-// AI assistants - set observeMe=false so Honcho doesn't model the AI
-const assistant = await honcho.peer("assistant", { configuration: { observeMe: false } });
-const supportBot = await honcho.peer("support-bot", { configuration: { observeMe: false } });
+// AI assistants can be observed too — leave observeMe on (the default) if you
+// want a model of the assistant.
+const assistant = await honcho.peer("assistant");
+
+// Deterministic bots (scripted/rule-based) - set observeMe=false; there's
+// nothing meaningful for Honcho to model.
+const notificationBot = await honcho.peer("notification-bot", { configuration: { observeMe: false } });
 ```
 
 ## 3. Multi-Peer Sessions
@@ -103,12 +111,13 @@ session = honcho.session("conversation-123")
 # User is observed (Honcho builds a model of them)
 user_config = SessionPeerConfig(observe_me=True, observe_others=True)
 
-# AI is NOT observed (no model built of the AI)
-ai_config = SessionPeerConfig(observe_me=False, observe_others=True)
+# A deterministic bot is NOT observed (no model built of it). An AI assistant
+# could stay observed instead — observe_me defaults to True.
+bot_config = SessionPeerConfig(observe_me=False, observe_others=True)
 
 session.add_peers([
     (user, user_config),
-    (assistant, ai_config)
+    (notification_bot, bot_config)
 ])
 ```
 
@@ -118,8 +127,10 @@ session.add_peers([
 const session = await honcho.session("conversation-123");
 
 await session.addPeers([
+    // A deterministic bot isn't observed; an AI assistant could stay observed
+    // instead (observeMe defaults to true).
     [user, { observeMe: true, observeOthers: true }],
-    [assistant, { observeMe: false, observeOthers: true }]
+    [notificationBot, { observeMe: false, observeOthers: true }]
 ]);
 ```
 

skills/honcho-mcp/SKILL.md

@@ -34,7 +34,7 @@ add_messages_to_session   session_id: "<session-id>"
                             - peer_id: "Assistant"     content: "<your exact reply>"
 ```
 
-**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold so Honcho actually reasons over them. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. Set `observe_me: false` on the assistant peer — you want a model of the user, not of yourself. Reasoning is asynchronous; don't poll or wait for it.
+**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold so Honcho actually reasons over them. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. Setting `observe_me: false` on the assistant peer skips building a model of it — reserve that for deterministic bots (nothing meaningful to model) or whenever you simply don't need a representation of the assistant; for an AI assistant it's perfectly fine to leave observation on. Reasoning is asynchronous; don't poll or wait for it.
 
 ## Other useful tools
 

skills/honcho-memory/SKILL.md

@@ -65,7 +65,7 @@ You need a Honcho API key — get one free at <https://app.honcho.dev> (starts w
 ## Rules of thumb
 
 - **Always record turns.** Memory only grows from messages you feed in. Recording is the one non-optional step.
-- **Don't observe yourself.** The assistant peer should be `observe_me: false` — you want a model of the user, not of the agent.
+- **Modeling the assistant is optional.** Setting `observe_me: false` on the assistant peer skips building a model of it — required only for deterministic bots (scripted output, nothing meaningful to model). For an AI assistant it's fine to leave observation on if you also want a model of the agent.
 - **One stable peer ID per entity.** Reuse the same `peer_id` for a person across every session and channel; splitting them (`user`, `user-web`, `user-discord`) builds separate representations and fragments memory.
 - **Scope sessions so reasoning actually fires.** Reasoning is token-batched per peer (~1,000 tokens within a session). Scope a session to one active interaction (per-conversation, per-channel, per-task, per-project); create a new one when context genuinely resets (new topic, new day), reuse it while context should keep accumulating. Many tiny sessions each stall below the threshold and never get reasoned over.
 - **Don't block on reasoning.** It's asynchronous. Respond now; the representation will be richer next time.