From aa9397457a40b8ea7fa3466ecdab6470b2ee813d Mon Sep 17 00:00:00 2001
From: ajspig <dragon@monstercode.com>
Date: Thu, 27 Aug 2026 13:57:18 -0400
Subject: [PATCH] chore(docs): clarify the scopes page and document
 create/status responses

The page now leads with projection rather than partition and points at the
scopes API; OpenAPI declares the 201/409/404 those routes actually return.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../features/advanced/scopes.mdx              | 15 ++++--------
 docs/v3/openapi.json                          | 24 +++++++++++++++++++
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/docs/v3/documentation/features/advanced/scopes.mdx b/docs/v3/documentation/features/advanced/scopes.mdx
index 07a91429..7fa2e42c 100644
--- a/docs/v3/documentation/features/advanced/scopes.mdx
+++ b/docs/v3/documentation/features/advanced/scopes.mdx
@@ -16,9 +16,8 @@ own tickets, a multi-tenant deployment where one human works across tenants.
 
 ## Projection, Not Partition
 
-A scope does not split a peer into pieces. The peer's representation stays
-whole; a scope is a **projection** of it — a view built only from the evidence
-in that scope's member sessions.
+The peer keeps one representation. A scope is a **projection** of it: a view
+built only from evidence in the member sessions.
 
 ```mermaid
 graph TB
@@ -42,8 +41,6 @@ graph TB
       style SC2 fill:#FFE0B2,stroke:#333,color:#000
 ```
 
-Three consequences worth internalizing:
-
 - **Sessions can belong to more than one scope.** Membership is many-to-many.
 - **Sessions can belong to no scope.** `onboarding-1` above is reachable
   by an unscoped request and by nothing else.
@@ -95,7 +92,7 @@ answer = user.chat("What did they say?", scope=["therapy", "intake"])
 
 Reach for this when the set of sessions is decided per-request, or when you want
 a quick boundary without provisioning a scope. See
-[Scoping Recall to Sessions](/v3/documentation/features/advanced/using-filters#scoping-recall-to-sessions)
+[Restricting Recall to Sessions](/v3/documentation/features/advanced/using-filters#restricting-recall-to-sessions)
 for the full allowlist rules.
 
 <Info>
@@ -296,7 +293,7 @@ requires `peer_target`). Like the session allowlist, it **fails closed**: a
 contradiction is rejected with a `422` rather than silently widened, a scope
 with no member sessions recalls nothing, and an empty list (`scope=[]`) is
 rejected rather than treated as "no boundary". Per-surface caps and error
-shapes are in the [API reference](/v3/api-reference/endpoint/peers/chat).
+shapes are in the [API reference](/v3/api-reference/endpoint/scopes/get-or-create-scope).
 
 ## Provenance, Not Topic
 
@@ -333,9 +330,7 @@ A few behaviors follow from how scopes are built:
   add-peers, set-peers, and remove-peers routes reject scope names and point you
   at `/scopes/{scope_id}/sessions` or the `scopes` field on session create.
 
-Honcho is open source — if you want to understand how scopes work under the
-hood, read the implementation:
-[`src/routers/scopes.py`](https://github.com/plastic-labs/honcho/blob/main/src/routers/scopes.py),
+If you want the exact mechanics for scopes, read: [`src/routers/scopes.py`](https://github.com/plastic-labs/honcho/blob/main/src/routers/scopes.py),
 [`src/crud/scope.py`](https://github.com/plastic-labs/honcho/blob/main/src/crud/scope.py),
 and [`src/deriver/scope_backfill.py`](https://github.com/plastic-labs/honcho/blob/main/src/deriver/scope_backfill.py).
 
diff --git a/docs/v3/openapi.json b/docs/v3/openapi.json
index dea289d2..b2bc0adf 100644
--- a/docs/v3/openapi.json
+++ b/docs/v3/openapi.json
@@ -2269,6 +2269,22 @@
               }
             }
           },
+          "201": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Scope" }
+              }
+            }
+          },
+          "409": {
+            "description": "Conflict",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
           "422": {
             "description": "Validation Error",
             "content": {
@@ -2536,6 +2552,14 @@
               }
             }
           },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
           "422": {
             "description": "Validation Error",
             "content": {