knightedcodemonkey · knightedcodemonkey · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026
diff --git a/README.md b/README.md
@@ -72,15 +72,18 @@ in the same UI.
 ## BYOT Guide
 
 - GitHub PAT setup and usage: [docs/byot.md](docs/byot.md)
+- OpenRouter key setup for AI chat: [docs/openrouter-byok.md](docs/openrouter-byok.md)
 
 ## Fine-Grained PAT Quick Setup
 
-For PR/BYOT and AI chat flows, use a fine-grained GitHub PAT and follow the
-existing setup guide:
+For PR/BYOT flows, use a fine-grained GitHub PAT and follow the setup guide:
 
 - Full setup and behavior: [docs/byot.md](docs/byot.md)
 - Repository permissions screenshot: [docs/media/byot-repo-perms.png](docs/media/byot-repo-perms.png)
-- Models permission screenshot: [docs/media/byot-model-perms.png](docs/media/byot-model-perms.png)
+
+For AI chat, connect an OpenRouter key from the chat drawer:
+
+- OpenRouter setup and limits: [docs/openrouter-byok.md](docs/openrouter-byok.md)
 
 ## License
 

diff --git a/docs/ai-chat-context-and-payload-strategy.md b/docs/ai-chat-context-and-payload-strategy.md
@@ -177,7 +177,7 @@ Potential ideas:
 
 Current strategy has focused Playwright coverage for the chat drawer behavior and context policy assertions in:
 
-- playwright/github-byot-ai.spec.ts
+- playwright/chat/ai-chat.spec.ts
 
 ## Scope note
 

diff --git a/docs/byot.md b/docs/byot.md
@@ -1,6 +1,6 @@
 # BYOT Setup for GitHub in @knighted/develop
 
-This guide explains how to create and use a fine-grained GitHub Personal Access Token (PAT) for the BYOT flow in `@knighted/develop`.
+This guide explains how to create and use a fine-grained GitHub Personal Access Token (PAT) for repository and pull-request workflows in `@knighted/develop`.
 
 ## What BYOT does in the app
 
@@ -11,7 +11,9 @@ BYOT controls are available by default. The token is used to:
 - let you choose which repository to work with
 - use PR context features (Open PR / Push Commit flows)
 
-The same token is also used for GitHub Models requests in AI chat flows.
+AI chat no longer uses the GitHub PAT. Chat uses a separate OpenRouter API key.
+
+- OpenRouter key setup for chat: [openrouter-byok.md](openrouter-byok.md)
 
 ## Privacy and storage behavior
 
@@ -24,21 +26,15 @@ The same token is also used for GitHub Models requests in AI chat flows.
 Create a fine-grained PAT in GitHub settings and grant the permissions below.
 
 - Repository permissions screenshot: [docs/media/byot-repo-perms.png](docs/media/byot-repo-perms.png)
-- Models permission screenshot: [docs/media/byot-model-perms.png](docs/media/byot-model-perms.png)
 
 <img src="media/byot-repo-perms.png" alt="Repository PAT permissions" width="560" />
-<img src="media/byot-model-perms.png" alt="Models PAT permission" width="560" />
 
 ### Repository permissions
 
 - Contents: Read and write
 - Pull requests: Read and write
 - Metadata: Read-only (required)
 
-### Account permissions
-
-- Models: Read-only
-
 ### Repository access scope
 
 Use either of these scopes depending on your needs:
@@ -55,7 +51,7 @@ Use either of these scopes depending on your needs:
 3. Paste token into the BYOT input and click add.
 4. Verify repository list loads.
 5. Select your target repository.
-6. Use AI chat as needed after connecting your token.
+6. Use PR and repository workflows after connecting your token.
 
 ## Screenshots
 

diff --git a/docs/localstorage-state.md b/docs/localstorage-state.md
@@ -8,9 +8,11 @@ This document is the source of truth for what `@knighted/develop` stores in `loc
 
 1. `knighted:develop:github-pat`
    - GitHub personal access token used for API calls.
-2. `knighted-develop:render-mode`
+2. `knighted:develop:openrouter-key`
+   - OpenRouter API key used by AI chat requests.
+3. `knighted-develop:render-mode`
    - Last selected render mode (`dom` or `react`).
-3. Theme/UI preference keys managed by layout theme modules.
+4. Theme/UI preference keys managed by layout theme modules.
 
 ## Not Allowed In localStorage
 

diff --git a/docs/openrouter-byok.md b/docs/openrouter-byok.md
@@ -0,0 +1,40 @@
+# OpenRouter BYOK Setup for AI Chat in @knighted/develop
+
+This guide explains how to create and use an OpenRouter API key for AI chat in `@knighted/develop`.
+
+## What this key does
+
+The OpenRouter key is used only for AI chat requests and model catalog requests in the chat drawer.
+
+- It enables chat completions against `https://openrouter.ai/api/v1/chat/completions`.
+- It enables loading model options from `https://openrouter.ai/api/v1/models`.
+
+The key is independent from the GitHub PAT used by PR and repository workflows.
+
+## Free model limits
+
+OpenRouter free models still require an API key.
+
+- Free models have no per-token charge.
+- Accounts without purchased credits are currently limited to 50 requests per day.
+- Accounts that have purchased at least $10 in credits are currently limited to 1000 requests per day.
+
+## Privacy and storage behavior
+
+- Your OpenRouter key is stored only in your browser `localStorage`.
+- The key is sent only to OpenRouter endpoints used by chat.
+- The key is never sent to GitHub endpoints.
+- You can remove it any time from the chat drawer key controls.
+
+## Create and connect an OpenRouter key
+
+1. Open https://openrouter.ai/keys and create an API key.
+2. Open the Chat drawer in `@knighted/develop`.
+3. Paste the key into the `OpenRouter API key` input.
+4. Click `Save OpenRouter API key`.
+5. Send a test prompt and confirm the assistant response appears.
+
+## Related docs
+
+- GitHub PAT setup for PR/repository workflows: [byot.md](byot.md)
+- Local storage keys: [localstorage-state.md](localstorage-state.md)
diff --git a/docs/openrouter-migration-plan.md b/docs/openrouter-migration-plan.md
@@ -43,7 +43,7 @@ Chat no longer depends on a selected repository. Local-mode users can chat to up
 editor tab with no GitHub connection at all. A selected repository remains useful context
 when one is connected, but it is never a precondition.
 
-## Implementation status (updated 2026-09-06)
+## Implementation status (updated 2026-09-07)
 
 ### Done
 
@@ -67,20 +67,21 @@ when one is connected, but it is never a precondition.
 - Tests and checks completed for the implemented behaviors:
   - Focused Playwright coverage added for intent gating, tab-context sending, and apply behavior.
   - Lint checks are passing.
-
-### Remaining
-
-- Phase 4 model catalog work is not yet implemented in runtime code:
-  - No live `/api/v1/models` fetch integration yet.
-  - Free vs paid grouping in the model picker is still pending.
-  - Tool-support filtering from live model metadata is still pending.
-- Phase 5 remains partial:
-  - Chat tests still live inside `playwright/github-byot-ai.spec.ts` rather than a split chat spec path.
-  - Dedicated OpenRouter usage docs listed below are not fully completed.
-- Live production verification still pending for exhaustion states:
-  - 402 out-of-credits behavior.
-  - 429 rate-limit behavior.
-- Optional one-time migration notice behavior is still pending.
+  - Chat test coverage is split into `playwright/chat/ai-chat.spec.ts`, with PR/BYOT
+    coverage retained in `playwright/github-byot-ai.spec.ts`.
+  - OpenRouter migration docs are in place (`docs/openrouter-byok.md`) and cross-linked
+    from README/BYOT docs.
+- Phase 4 completed in runtime code:
+  - Live `/api/v1/models` catalog fetch is wired in `src/modules/chat/api/models.js`.
+  - Model picker groups models into Free and Paid sections.
+  - Model catalog entries are filtered to tool-capable models.
+
+### Remaining (non-blocking)
+
+- Optional follow-up coverage:
+  - Explicit targeted specs for 402/429 status messaging and catalog-fetch degradation.
+- Optional UX follow-up:
+  - One-time migration notice on first load after upgrade.
 
 ### Correction to a common assumption