From 9e6c79f5be3bda0e2d1c32760b908fcf9fdccb66 Mon Sep 17 00:00:00 2001
From: outpoints <12377381+outpoints@users.noreply.github.com>
Date: Fri, 4 Sep 2026 15:51:06 -0700
Subject: [PATCH] docs(honcho): document workspace routing and provider context

---
 .../developer-guide/memory-provider-plugin.md | 25 +++++++++++++++++++
 website/docs/user-guide/features/honcho.md    |  6 ++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/website/docs/developer-guide/memory-provider-plugin.md b/website/docs/developer-guide/memory-provider-plugin.md
index 86b1f60de5..a006eca911 100644
--- a/website/docs/developer-guide/memory-provider-plugin.md
+++ b/website/docs/developer-guide/memory-provider-plugin.md
@@ -98,6 +98,31 @@ class MyMemoryProvider(MemoryProvider):
     # ... implement remaining methods
 ```
 
+### Initialization context
+
+`AIAgent` passes session context through `MemoryManager.initialize_all()` to
+`initialize(session_id, **kwargs)`. Accept `**kwargs` and tolerate missing optional
+fields; callers may initialize a provider without an agent or a session database.
+
+| Keyword | Meaning |
+|---|---|
+| `hermes_home` | Active profile's storage directory. |
+| `platform` | Session surface, such as `cli`, `gui`, `acp`, or `telegram`. |
+| `session_title` | Stored session title, when available. A display label is not necessarily a user-selected identity. |
+| `session_title_source` | Stored title provenance, when available: `derived`, `llm`, or `user`. Automatic sources must not be mistaken for explicit identity overrides; missing provenance retains a provider's legacy behavior. Shared constants live in `hermes_state_common.py`. |
+| `cwd` | Non-empty logical workspace supplied as `AIAgent(cwd=...)`, available before provider initialization. Omitted for `None` or an empty string. |
+| `gateway_session_key` | Stable messaging-chat identity for per-chat session isolation. |
+| `user_id`, `user_id_alt`, `user_name`, `chat_id` | Gateway identity fields, included when present. |
+| `agent_identity` | Active profile name, when available. |
+| `agent_workspace`, `agent_context` | Runtime agent scope (`hermes` and `primary` for the main agent). |
+
+Do not assume `os.getcwd()` identifies the conversation's workspace: one Desktop
+or gateway backend can serve several sessions. If `cwd` is absent and directory
+routing is needed, `agent.runtime_cwd.resolve_agent_cwd()` honors the session cwd
+context, then scoped `terminal.cwd` (carried internally as `TERMINAL_CWD`), then
+the launch directory. Construction-time workspace metadata does not require
+changing the process cwd or rebuilding an existing conversation's system prompt.
+
 ## Required Methods
 
 ### Core Lifecycle
diff --git a/website/docs/user-guide/features/honcho.md b/website/docs/user-guide/features/honcho.md
index efa0eab197..f302e694f9 100644
--- a/website/docs/user-guide/features/honcho.md
+++ b/website/docs/user-guide/features/honcho.md
@@ -140,7 +140,11 @@ When pointing Hermes at a self-hosted Honcho server, `hermes honcho setup` (and
 - `per-repo` — one session per git repository.
 - `global` — single session across all directories.
 
-Automatically generated Hermes titles are display metadata and do not override `sessionStrategy`. An explicit user title remains an intentional session-name override for non-gateway, non-`per-session` sessions.
+Directory-based strategies and manual `sessions` mappings use the logical session working directory, not the backend's launch directory. Desktop/TUI project workspaces and ACP session directories are passed during agent construction, including deferred builds. When no directory is supplied, Honcho uses the runtime cwd resolver: session context, then the scoped `terminal.cwd` setting, then the process launch directory.
+
+Messaging gateways keep their stable per-chat session key regardless of strategy or title. For other sessions, `per-session` identity takes priority, followed by a manual directory mapping, an explicit title, and the configured strategy.
+
+Automatically generated Hermes titles (`derived` or `llm`) are display metadata and do not override `sessionStrategy`. An explicit user title remains an intentional session-name override for non-gateway, non-`per-session` sessions without a manual mapping.
 
 Sessions created before title provenance was recorded retain legacy behavior: because an old automatic title cannot be distinguished from an old user title, a title with no source is treated as an explicit override.