knightedcodemonkey · knightedcodemonkey · Sep 7, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 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
@@ -16,7 +16,7 @@ Each request includes a system prompt with policy guidance, then augments that p
 
 Primary implementation:
 
-- src/modules/github/chat/payload.js
+- src/modules/chat/payload.js
 
 ### 2. Repository context
 
@@ -29,7 +29,7 @@ Each request includes repository targeting context as a dedicated system message
 
 Primary implementation:
 
-- src/modules/github/chat/drawer.js
+- src/modules/chat/drawer.js
 
 ### 3. Editor context (Send tab content)
 
@@ -44,8 +44,8 @@ This context is designed to support dynamic proposal targeting by tab id/path an
 
 Primary implementation:
 
-- src/modules/github/chat/active-tab-context.js
-- src/modules/github/chat/drawer.js
+- src/modules/chat/active-tab-context.js
+- src/modules/chat/drawer.js
 
 ### 4. Tooling model
 
@@ -62,9 +62,9 @@ Contract:
 
 Primary implementation:
 
-- src/modules/github/chat/proposals.js
-- src/modules/github/chat/tab-target-resolver.js
-- src/modules/github/chat/drawer.js
+- src/modules/chat/proposals.js
+- src/modules/chat/tab-target-resolver.js
+- src/modules/chat/drawer.js
 
 ### 5. Apply and undo behavior
 
@@ -74,8 +74,8 @@ Primary implementation:
 
 Primary implementation:
 
-- src/modules/github/chat/drawer.js
-- src/modules/github/chat/tab-scoped-undo-state.js
+- src/modules/chat/drawer.js
+- src/modules/chat/tab-scoped-undo-state.js
 
 ### 6. Payload size controls and summary strategy
 
@@ -88,7 +88,7 @@ The payload builder includes bounded-conversation controls:
 
 Primary implementation:
 
-- src/modules/github/chat/payload.js
+- src/modules/chat/payload.js
 
 ### 7. Fallback and transport behavior
 
@@ -98,8 +98,8 @@ Primary implementation:
 
 Primary implementation:
 
-- src/modules/github/chat/drawer.js
-- src/modules/github/api/chat.js
+- src/modules/chat/drawer.js
+- src/modules/chat/api/completions.js
 
 ## Why this approach
 
@@ -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/next-steps.md b/docs/next-steps.md
@@ -26,10 +26,38 @@ Focused follow-up work for `@knighted/develop`.
    - Suggested implementation prompt:
      - "Evaluate and optionally optimize @knighted/develop GitHub file upsert behavior. Compare metadata-first preflight GET+PUT against optimistic PUT with retry-on-missing-sha for existing files. Keep current reliability guarantees and avoid reintroducing noisy false-positive failures. If implementing a hybrid/configurable strategy, keep defaults conservative, update docs, and validate with npm run lint plus targeted Playwright PR drawer flows."
 
-5. **Promise handling conventions (consistency of intent)**
-   - Define a project default: use `async`/`await` with `try`/`catch` for most async control flow.
-   - Keep Promise chains where they better express intent (for example, fire-and-forget paths with explicit `.catch()` to avoid unhandled rejections, or concise pass-through composition).
-   - Document this as an intent-first rule so mixed syntax is acceptable only when deliberate and easy to reason about.
-   - Add a lightweight lint/review rule to flag mixed async styles in the same flow unless there is a clear justification.
+5. **Document async handling conventions (consistency of intent)**
+   - The codebase already uses `async`/`await` for most multi-step async control flow.
+   - Keep Promise chains where they better express intent, such as concurrent composition,
+     concise pass-through composition, or fire-and-forget paths with explicit `.catch()` to
+     avoid unhandled rejections.
+   - Document this intent-first convention for future changes and code review. Do not pursue
+     a broad refactor or add a rigid lint rule solely to make syntax uniform.
    - Suggested implementation prompt:
-     - "Define and apply async handling conventions in @knighted/develop with consistency of intent: default to async/await + try/catch, allow Promise chains for explicit fire-and-forget and concise composition, and require explicit .catch on unawaited promises. Update docs and enforce via lint/review guidance without broad no-op refactors. Validate with npm run lint and targeted Playwright runs."
+     - "Document the existing async handling convention in @knighted/develop: prefer
+       async/await for multi-step control flow, allow Promise chains for deliberate
+       concurrency or fire-and-forget work, and require explicit rejection handling for
+       unawaited promises. Make only targeted cleanup changes where intent is unclear."
+
+6. **Render model Markdown responses as safe HTML**
+   - Evaluate rendering assistant Markdown as formatted HTML instead of displaying the
+     response as plain text, including fenced code blocks, inline code, links, lists, and
+     other common response structures.
+   - Compare small browser-compatible Markdown parsers that work with the CDN-first
+     runtime, such as `marked` or `markdown-it`, and load the chosen dependency lazily
+     through the existing CDN provider and fallback mechanism.
+   - Treat model output as untrusted input. Pair Markdown rendering with an explicit HTML
+     sanitization policy, such as DOMPurify or an equivalent sanitizer, and restrict link
+     protocols and external navigation behavior.
+   - Preserve the raw Markdown response for proposal extraction, streaming updates, and
+     conversation state; rendered HTML should be a presentation layer only.
+   - Define behavior for incomplete streamed Markdown, unsupported syntax, rendering
+     failures, and environments where the CDN dependency cannot be loaded. Plain-text
+     rendering should remain a usable fallback.
+   - Suggested implementation prompt:
+     - "Add safe Markdown rendering for @knighted/develop AI chat responses. Evaluate a
+       small CDN-compatible parser such as marked or markdown-it plus an HTML sanitizer,
+       load both lazily through the existing CDN fallback system, preserve raw Markdown
+       for proposal extraction and chat state, and keep plain-text rendering as the
+       failure fallback. Handle streamed/incomplete Markdown, safe links, code blocks,
+       and XSS cases. Validate with npm run lint and focused Playwright chat coverage."
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)