From c45abdb379bb850488f6b7ff38ffc6370690f652 Mon Sep 17 00:00:00 2001
From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com>
Date: Thu, 11 Jun 2026 15:23:13 -0400
Subject: [PATCH] Document X-Kernel-Project-Id resolution rules on the Projects
 page

Three updates, all matching middleware behavior verified end-to-end against
kernel/kernel#2387:

- Fix the unscoped-request claim: without the header, requests act on the
  org's default project, not org-wide. (Same stale framing kernel/kernel#2386
  fixes in the OpenAPI descriptions.)
- Add a Resolution rules section: unknown/archived project returns a coded
  404 (project_not_found); naming the default project is equivalent to
  omitting the header; scoped keys 403 on mismatched headers.
- Note the header accepts a project ID or name.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 info/projects.mdx | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/info/projects.mdx b/info/projects.mdx
index 4f3cc90..79ff2f4 100644
--- a/info/projects.mdx
+++ b/info/projects.mdx
@@ -25,7 +25,7 @@ A project must also be empty before it can be deleted — archive or remove its
 
 ## Scoping Requests to a Project
 
-Pass the `X-Kernel-Project-Id` header on any API request to scope it to a specific project. Without the header (and without a project-scoped API key), requests operate org-wide.
+Pass the `X-Kernel-Project-Id` header — a project ID or name — on any API request to scope it to a specific project. Without the header (and without a project-scoped API key), requests act on your organization's **default project**: reads return the default project's resources, and writes create resources in it.
 
 ```bash
 curl https://api.onkernel.com/browsers \
@@ -33,6 +33,17 @@ curl https://api.onkernel.com/browsers \
   -H "X-Kernel-Project-Id: proj_abc123"
 ```
 
+### Resolution rules
+
+- **Unknown or archived project** — a header naming a project that doesn't exist or isn't active fails with `404 Not Found`:
+
+  ```json
+  { "code": "project_not_found", "message": "Project not found or inactive" }
+  ```
+
+- **The default project is the baseline** — naming your organization's default project is exactly equivalent to omitting the header, for both reads and writes.
+- **Scoped keys reject mismatches** — with a project-scoped API key, a header naming any other project fails with `403 Forbidden` (see [API keys](#api-keys) below).
+
 ### SDK usage
 
 Set the header on the client so every request is scoped to the project. You can also override it per-request.