chore(docs): correct scope arms, listing, and read-surface pointers

The Accepts row mixed named-scope with the allowlist arm, kind=scope on
the peers list does not return facade ids, and chat/context/search never
mentioned scope=.

Co-authored-by: Cursor <cursoragent@cursor.com>

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

@@ -95,7 +95,7 @@ not the total number of items ever processed.
 </Note>
 
 The `queue_status` method can take additional
-parameters to narrow the status to a specific work unit:
+parameters to filter the status by a matching observer, sender, or session:
 
 <CodeGroup>
 ```python Python

docs/v3/documentation/features/advanced/scopes.mdx

@@ -48,7 +48,8 @@ graph TB
   that name it; it does not hide the sessions from requests that don't.
 
 <Warning>
-Scopes are a recall boundary, not an authorization boundary. Access can be scoped by workspace, session, or peer boundaries.
+Scopes are a recall boundary, not an authorization boundary. Who may call the
+API is still governed by workspace, session, and peer keys.
 </Warning>
 
 ## The Two Arms
@@ -62,7 +63,7 @@ wrong one is the most common mistake with this feature.
 | **Conclusions** | All levels — `explicit`, plus `deductive` / `inductive` reasoned **within** the scope | `explicit` only |
 | **Reasoning chains** | Available | Unavailable |
 | **Setup required** | Yes — create the scope, add sessions, wait for backfill | None — pass session IDs ad hoc |
-| **Accepts** | One scope name, or a list of up to 100 | Up to 1,000 session IDs |
+| **Accepts** | One scope name | A list of up to 100 scope names, or up to 1,000 session IDs |
 
 ### Named scope: depth
 
@@ -109,7 +110,7 @@ from honcho import Honcho
 
 honcho = Honcho(workspace_id="my-app")
 
-# Get or create — idempotent
+# Get or create — idempotent; passing metadata updates the existing scope
 therapy = honcho.scope("therapy")
 
 # Add existing sessions (max 100 per call)
@@ -133,7 +134,7 @@ import { Honcho } from "@honcho-ai/sdk";
 
 const honcho = new Honcho({ workspaceId: "my-app" });
 
-// Get or create — idempotent
+// Get or create — idempotent; passing metadata updates the existing scope
 const therapy = await honcho.scope("therapy");
 
 // Add existing sessions (max 100 per call)
@@ -180,7 +181,8 @@ curl -X DELETE "$HONCHO_URL/v3/workspaces/my-app/scopes/therapy/sessions/therapy
 </CodeGroup>
 
 Scope IDs are unprefixed, must match `^[a-zA-Z0-9_-]+$`, and are at most 506
-characters.
+characters. Get-or-create is idempotent: if the scope already exists, the same
+call returns it, and any `metadata` you pass is written onto it.
 
 <Note>
 Every scopes route — and every read that passes `scope` — requires a
@@ -234,7 +236,7 @@ empty result means none have — not that the scope is empty.
 
 ## Reading Through a Scope
 
-`scope` is accepted on four surfaces:
+`scope` is accepted on these surfaces:
 
 | Surface | Accepts | Notes |
 |---------|---------|-------|
@@ -242,6 +244,7 @@ empty result means none have — not that the scope is empty.
 | `peer.representation()` | one scope or a list | Confines conclusion recall |
 | [`session.context()`](/v3/documentation/features/get-context) | one scope only | Perspective source for `peer_target`'s representation and card. Requires `peer_target`; mutually exclusive with `peer_perspective` |
 | `honcho.search()` | one scope only | Restricts message search to the scope's member sessions |
+| `honcho.chat()` | one scope or a list | Always the allowlist arm — even a single name. There is no observer to swap |
 
 <CodeGroup>
 ```python Python
@@ -321,8 +324,11 @@ A few behaviors follow from how scopes are built:
 
 - **The `scope.` prefix is reserved.** Creating a peer, or adding a peer to a
   session, with a `scope.`-prefixed name is rejected.
-- **Scopes are hidden from peer listings by default.** Pass `kind="scope"` to
-  list only scopes, or `kind="all"` to see both.
+- **List scopes through the scopes surface.** `honcho.scopes()` /
+  `POST /scopes/list` returns unprefixed ids. Peer listings hide scopes by
+  default; `kind="scope"` on `POST /peers/list` returns the backing peers named
+  `scope.<id>`, and `kind="all"` includes both regular peers and those backing
+  peers.
 - **A scope can't be observed.** No representation is formed *of* a scope, so a
   scope is rejected in any `target` / observed position, including as a dream
   target.

docs/v3/documentation/features/advanced/search.mdx

@@ -49,6 +49,20 @@ import { Honcho } from "@honcho-ai/sdk";
 ```
 </CodeGroup>
 
+Pass `scope` on workspace search to restrict matches to that
+[scope](/v3/documentation/features/advanced/scopes)'s member sessions. A scope
+with no members returns nothing.
+
+<CodeGroup>
+```python Python
+results = honcho.search("budget planning", scope="therapy")
+```
+
+```typescript TypeScript
+const results = await honcho.search("budget planning", { scope: "therapy" });
+```
+</CodeGroup>
+
 ### Session Search
 
 Search within a specific session's conversation history:

docs/v3/documentation/features/chat.mdx

@@ -115,6 +115,12 @@ constrained `filters` body on the endpoint. See
 [Scoping Recall to Sessions](/v3/documentation/features/advanced/using-filters#scoping-recall-to-sessions)
 for the accepted shapes and for what an allowlist changes about the answer.
 
+Pass `scope="therapy"` to answer from that [scope](/v3/documentation/features/advanced/scopes)'s
+own representation of the peer. A list (`scope=["therapy", "intake"]`) is an
+allowlist of those scopes' sessions, not named-scope depth.
+`honcho.chat(scope=)` is always the allowlist arm, even with one name. Details
+are on the [scopes page](/v3/documentation/features/advanced/scopes#the-two-arms).
+
 ## Structured Outputs
 
 When your application needs a machine-readable answer instead of prose, pass a schema as `response_format` and the answer is guaranteed to conform to it:

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

@@ -99,7 +99,7 @@ context = session.context(summary=False, tokens=2000)
 
 ### Peer Representation in Context
 
-You can include a peer's [representation](/v3/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.
+You can include a peer's [representation](/v3/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. Pass `scope` with `peer_target` to use a [named scope](/v3/documentation/features/advanced/scopes) as the perspective source (`scope` is mutually exclusive with `peer_perspective`).
 
 <CodeGroup>
 ```python Python
@@ -119,6 +119,14 @@ context = session.context(
     peer_target="user-123",
     peer_perspective="assistant"  # From assistant's viewpoint
 )
+
+# Or use a named scope as the perspective source (requires peer_target;
+# mutually exclusive with peer_perspective)
+context = session.context(
+    tokens=2000,
+    peer_target="user-123",
+    scope="therapy",
+)
 ```
 
 ```typescript TypeScript
@@ -139,6 +147,14 @@ context = session.context(
       peerTarget: "user-123",
       peerPerspective: "assistant"  // From assistant's viewpoint
     });
+
+    // Or use a named scope as the perspective source (requires peerTarget;
+    // mutually exclusive with peerPerspective)
+    const scopedContext = await session.context({
+      tokens: 2000,
+      peerTarget: "user-123",
+      scope: "therapy",
+    });
 })();
 ```
 </CodeGroup>
@@ -211,6 +227,7 @@ context = session.context(
 | `tokens` | `int` | Maximum tokens to include |
 | `peer_target` | `str` | Peer ID to include representation for |
 | `peer_perspective` | `str` | Peer ID for perspective (requires peer_target) |
+| `scope` | `str` | Named scope as the perspective source for `peer_target`'s representation and card. Requires `peer_target`; mutually exclusive with `peer_perspective`. See [Scopes](/v3/documentation/features/advanced/scopes) |
 | `search_query` | `str` | Query for semantic search (requires peer_target) |
 | `limit_to_session` | `bool` | Limit to session conclusions only |
 | `search_top_k` | `int` | Semantic search results to include (1-100) |