docs: update GitHub App setup instructions and clarify secret naming conventions

Co-authored-by: Copilot <copilot@github.com>
Signed-off-by: Krishna GSVV <krishnagsvv@gmail.com>

Author: VKrishna04

.env.example

@@ -26,6 +26,15 @@ GITHUB_APP_CLIENT_SECRET=
 # Webhook secret used to verify incoming GitHub webhooks
 GITHUB_APP_WEBHOOK_SECRET=
 
+# NOTE: GitHub Actions disallows repository secret names beginning with `GITHUB_`.
+# When adding these values as GitHub repository secrets (for CI), use the
+# `CODELEDGER_GH_*` names instead. Example mapping:
+# CODELEDGER_GH_APP_ID -> (value of GITHUB_APP_ID)
+# CODELEDGER_GH_APP_PRIVATE_KEY -> (contents of GITHUB_APP_PRIVATE_KEY file)
+# CODELEDGER_GH_APP_CLIENT_ID -> (value of GITHUB_APP_CLIENT_ID)
+# CODELEDGER_GH_APP_CLIENT_SECRET -> (value of GITHUB_APP_CLIENT_SECRET)
+# CODELEDGER_GH_APP_WEBHOOK_SECRET -> (value of GITHUB_APP_WEBHOOK_SECRET)
+
 # Application secrets
 # Secret used to sign session cookies / JWTs (choose a long random string)
 SESSION_SECRET=

README.md

@@ -57,7 +57,7 @@ If you are a developer compiling the extension from source and do not want to us
 1. Go to **GitHub Developer Settings** -> **GitHub Apps** -> **New GitHub App**.
 2. **GitHub App name:** `CodeLedger Dev` (or similar).
 3. **Homepage URL:** (Optional, your GitHub profile/repo URL).
-4. **Callback URL:** If using a web-backend like Cloudflare Workers, use `https://<your-worker-url>.workers.dev/auth/github/callback`. For Chrome Extension direct flows, use `https://<extension-id>.chromiumapp.org/`.
+4. **Callback URL:** If using a web-backend like Cloudflare Workers, use `https://<your-worker-url>.workers.dev/api/auth/github/callback`. For Chrome Extension direct flows, use `https://<extension-id>.chromiumapp.org/`.
 5. **Webhook:** Disable Webhook (Active: false).
 6. **Permissions:**
    * **Repository Permissions:**
@@ -76,7 +76,7 @@ sequenceDiagram
     participant GitHub as GitHub OAuth API
 
     User->>Extension: Clicks "Connect GitHub"
-    Extension->>CFWorker: Opens popup to /auth/github
+    Extension->>CFWorker: Opens popup to /api/auth/github
     CFWorker->>GitHub: Redirects user to GitHub Authorize URI
     GitHub-->>User: Prompts for permission (repo scope)
     User->>GitHub: Approves access

docs/ARCHITECTURE.md

@@ -11,10 +11,10 @@ graph TD
     Ext[Browser Extension] -->|Observes| LeetCode[LeetCode]
     Ext -->|Observes| GFG[GeeksForGeeks]
     Ext -->|Observes| CF[Codeforces]
-    
+
     Ext -->|Event: problem:solved| EventBus[Event Bus]
     EventBus --> BG[Background Service Worker]
-    
+
     BG --> Storage[Local chrome.storage]
     BG -->|AI Review| LLM[Gemini/OpenAI/Ollama]
     BG -->|GraphQL/REST| Git[GitHub API - Tree Commit]
@@ -41,7 +41,7 @@ sequenceDiagram
 ```
 
 **Explanation:**
-Upon installation or startup, the Service Worker initializes `BasePlatformHandler`, `BaseGitHandler`, and `BaseAIHandler` instances. This design means that adding a new platform (like HackerRank) only requires writing a single isolated class and registering it. 
+Upon installation or startup, the Service Worker initializes `BasePlatformHandler`, `BaseGitHandler`, and `BaseAIHandler` instances. This design means that adding a new platform (like HackerRank) only requires writing a single isolated class and registering it.
 
 ## 3. GitHub Secure OAuth Flow
 
@@ -51,11 +51,11 @@ Since MV3 service workers and cross-origin isolation make OAuth tricky without h
 sequenceDiagram
     participant User
     participant Ext as CodeLedger
-    participant CF as Cloudflare Worker (/auth/github)
+    participant CF as Cloudflare Worker (/api/auth/github)
     participant GH as GitHub OAuth
-    
+
     User->>Ext: Clicks Login
-    Ext->>CF: Popup window to /auth/github
+    Ext->>CF: Popup window to /api/auth/github
     CF->>GH: Redirect to authorization UI
     User->>GH: Approves
     GH->>CF: Callback with ?code=XXX
@@ -76,16 +76,16 @@ CodeLedger uses the GitHub Git Data APIs (`/git/trees`, `/git/commits`, `/git/re
 sequenceDiagram
     participant BG as Background Worker
     participant GH as GitHub API (Trees)
-    
+
     BG->>GH: GET /git/refs/heads/main
     GH-->>BG: Return base commit SHA
-    
+
     BG->>GH: POST /git/trees (Files & prev SHA)
     GH-->>BG: Return new tree SHA
-    
+
     BG->>GH: POST /git/commits (Tree SHA & Parent SHA)
     GH-->>BG: Return new commit SHA
-    
+
     BG->>GH: PATCH /git/refs/heads/main (New commit SHA)
     GH-->>BG: Branch Updated
 ```

docs/GITHUB_APP_SETUP.md

@@ -6,9 +6,9 @@ This document provides recommended values and a manifest to create the GitHub Ap
 
 **Homepage URL**: https://codeledger.vkrishna04.me
 
-**Callback URL (OAuth / redirect)**: https://api.codeledger.vkrishna04.me/auth/github/callback
+**Callback URL (OAuth / redirect)**: https://codeledger.vkrishna04.me/api/auth/github/callback
 
-**Webhook URL**: https://api.codeledger.vkrishna04.me/webhook/github
+**Webhook URL**: https://codeledger.vkrishna04.me/api/webhook/github
 
 **Webhook secret**: generate a strong random secret and store it as an environment variable in your Cloudflare Worker (e.g. `GITHUB_APP_WEBHOOK_SECRET`).
 
@@ -49,8 +49,8 @@ Example GitHub App manifest (use via GitHub App creation flow):
 {
   "name": "Code Ledger",
   "url": "https://codeledger.vkrishna04.me",
-  "hook_attributes": { "url": "https://api.codeledger.vkrishna04.me/webhook/github" },
-  "redirect_url": "https://api.codeledger.vkrishna04.me/auth/github/callback",
+  "hook_attributes": { "url": "https://codeledger.vkrishna04.me/api/webhook/github" },
+  "redirect_url": "https://codeledger.vkrishna04.me/api/auth/github/callback",
   "public": false,
   "default_permissions": {
     "metadata": "read",
@@ -87,7 +87,7 @@ Manual Cloudflare Worker deployment (via Cloudflare dashboard):
 2. In the Cloudflare dashboard, create a new Worker, choose "Upload a script" or use the online editor and paste `worker/src/index.js`.
 3. In Worker settings, add the environment variables listed above under "Variables" (or "Secrets/Environment").
 4. If your Worker serves static assets (worker/public), configure a KV or Pages deployment, or copy the static assets into the Worker script's `serveStatic` root.
-5. Test the endpoints: `/auth/github` should redirect to GitHub, `/auth/github/callback` should return a small HTML page that posts the token back to the opener window.
+5. Test the endpoints: `/api/auth/github` should redirect to GitHub, `/api/auth/github/callback` should return a small HTML page that posts the token back to the opener window.
 
 Notes on the two auth modes:
 
@@ -97,21 +97,42 @@ Notes on the two auth modes:
 
 Deploying the worker from this repository (recommended GitHub Actions flow):
 
-- Add repository secrets: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_ID`, `GITHUB_APP_WEBHOOK_SECRET`.
-- Create a GitHub Actions workflow that runs `wrangler publish` (or `wrangler deploy`) using those secrets.
+- Repository secrets required by CI (use these exact names):
+  - `CF_API_TOKEN` — Cloudflare API token with permissions to manage Workers, KV, and Routes.
+  - `CF_ACCOUNT_ID` — Your Cloudflare account ID (32-char string).
+  - `CANONICAL_KV_ID` — Workers KV namespace id used for `CANONICAL_MAP` binding.
+  - `CANONICAL_UPLOAD_TOKEN` — Admin token used by the Worker to accept canonical-map uploads.
+  - `SESSION_SECRET` — Long random signing secret for session/JWTs.
+  - `CODELEDGER_GH_APP_PRIVATE_KEY` — GitHub App private key (PEM contents).
+  - `CODELEDGER_GH_APP_ID` — GitHub App numeric ID.
+  - `CODELEDGER_GH_APP_CLIENT_ID` — (optional) OAuth client id if using OAuth flow.
+  - `CODELEDGER_GH_APP_CLIENT_SECRET` — (optional) OAuth client secret if using OAuth flow.
+  - `CODELEDGER_GH_APP_WEBHOOK_SECRET` — Webhook secret to validate GitHub webhooks.
 
-Quick local steps to publish the worker (you must have `wrangler` installed):
+> Note: GitHub Actions disallows repository secret names that begin with `GITHUB_`. That is why the CI and repo are configured to use the `CODELEDGER_GH_*` mapping instead of `GITHUB_*`.
+
+- The included workflow (`.github/workflows/deploy-worker.yml`) will:
+  1. Generate a runtime `worker/wrangler.toml` using `CF_ACCOUNT_ID` and `CANONICAL_KV_ID`.
+  2. Upload the runtime secrets listed above to Cloudflare (via `wrangler secret put`).
+  3. Publish the Worker to the route `https://codeledger.vkrishna04.me/*` (landing + API).
+
+Quick local steps to run a smoke test (no CI required):
 
 ```powershell
 cd worker
-wrangler login
-wrangler publish
+npm ci
+# Start a local dev server for the Worker (requires Wrangler installed)
+npx wrangler dev --local
 ```
 
+Notes:
+- If you prefer CI-based deployment, ensure `CF_API_TOKEN` and all required secrets are set in the repository before triggering the workflow — otherwise the workflow will fail early during validation.
+- If you want me to trigger the workflow now, I can do that (I will check whether `CF_API_TOKEN` exists in repo secrets first). Alternatively I can run `wrangler dev` locally for a smoke test instead.
+
 If you want, I can:
 
 - Add a `docs` page with a sample `worker/.env.example` and the minimal `worker/src/index.js` auth routes wired to the App settings.
-- Prepare a GitHub Actions workflow that deploys the worker using `CLOUDFLARE_API_TOKEN`.
+- Prepare or run the GitHub Actions workflow that deploys the worker using `CF_API_TOKEN`.
 
 ---
 File references:

docs/OPENAPI.yaml

@@ -6,7 +6,7 @@ info:
 
 # Servers: update these to match `CONSTANTS.URLS` in src/core/constants.js.
 servers:
-  - url: https://api.codeledger.vkrishna04.me
+  - url: https://codeledger.vkrishna04.me/api
     description: Production Cloudflare OAuth Bridge (AUTH_WORKER)
   - url: https://codeledger.vkrishna04.me
     description: Project landing / public docs

prompt.md

@@ -28,7 +28,7 @@ React + Vite + Tailwind, driven entirely by a `settings.json` in the repo. Dynam
 | License       | Apache 2.0                                                                             |
 | Author        | VKrishna04                                                                             |
 | Domain        | `codeledger.vkrishna04.me`                                                             |
-| Auth worker   | `https://api.codeledger.vkrishna04.me`                                                 |
+| Auth worker   | `https://codeledger.vkrishna04.me/api`                                                 |
 | Telemetry     | `https://counter.vkrishna04.me` (CFlair-Counter, deployed)                             |
 | Canonical map | `https://raw.githubusercontent.com/vkrishna04/codeledger/main/data/canonical-map.json` |
 
@@ -414,7 +414,7 @@ export const CONSTANTS = Object.freeze({
   // ── External URLs (all user-overridable via Settings > Advanced) ──
   URLS: {
     LANDING:            'https://codeledger.vkrishna04.me',
-    AUTH_WORKER:        'https://api.codeledger.vkrishna04.me',
+    AUTH_WORKER:        'https://codeledger.vkrishna04.me/api',
     TELEMETRY:          'https://counter.vkrishna04.me',
     CANONICAL_MAP_RAW:  'https://raw.githubusercontent.com/vkrishna04/codeledger/main/data/canonical-map.json',
     CANONICAL_MAP_SCHEMA: 'https://raw.githubusercontent.com/vkrishna04/codeledger/main/data/schema/canonical-map.schema.json',

src/core/constants.js

@@ -104,6 +104,15 @@ export const CONSTANTS = Object.freeze({
       supportsLiveFetch: true,
       keyRequired: false,
     },
+    openrouter: {
+      id: "openrouter",
+      name: "OpenRouter",
+      endpoint: "https://api.openrouter.ai/v1",
+      modelsEndpoint: "https://api.openrouter.ai/v1/models",
+      defaultModel: "openrouter/gpt-4o-mini",
+      supportsLiveFetch: true,
+      keyRequired: true,
+    },
   },
 
   AI_DEFAULT_PRIMARY: "gemini",

src/core/model-fetch.js

@@ -126,6 +126,29 @@ export async function fetchModelsForProvider(providerId) {
         // ignore
       }
     }
+
+    if (providerId === "openrouter") {
+      const key = await getFirstKeyForProvider("openrouter");
+      if (!key) return [];
+      const me = provider.modelsEndpoint;
+      const ep = me ? me.replace(/\/$/, "") : `${epFor()}/models`;
+      try {
+        const res = await fetch(ep, {
+          headers: { Authorization: `Bearer ${key}` },
+        });
+        if (res.ok) {
+          const data = await res.json();
+          const orModels = (data.data || data.models || []).map((m) => ({
+            id: m.id || m.name,
+            label: `${provider.name}: ${m.name || m.id}`,
+            group: provider.name,
+          }));
+          models.push(...orModels);
+        }
+      } catch (e) {
+        // ignore
+      }
+    }
   } catch (e) {
     // best-effort
   }
@@ -219,6 +242,22 @@ export async function testAIKey(providerId, key) {
       }
     }
 
+    if (providerId === "openrouter") {
+      const ep = me
+        ? me.replace(/\/$/, "")
+        : `${(provider.endpoint || "").replace(/\/$/, "")}/models`;
+      try {
+        const res = await fetch(ep, {
+          headers: { Authorization: `Bearer ${key}` },
+        });
+        if (res.ok) return { ok: true };
+        const text = await res.text();
+        return { ok: false, error: `Status ${res.status}: ${text}` };
+      } catch (e) {
+        return { ok: false, error: e.message };
+      }
+    }
+
     return { ok: false, error: "Provider does not support key testing" };
   } catch (e) {
     return { ok: false, error: e.message };

src/handlers/ai/claude/index.js

@@ -3,41 +3,47 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BaseAIHandler } from '../../_base/BaseAIHandler.js';
-import { APIKeyPool } from '../../../core/api-key-pool.js';
-import { Storage } from '../../../core/storage.js';
-import { CONSTANTS } from '../../../core/constants.js';
+import { BaseAIHandler } from "../../_base/BaseAIHandler.js";
+import { APIKeyPool } from "../../../core/api-key-pool.js";
+import { Storage } from "../../../core/storage.js";
+import { CONSTANTS } from "../../../core/constants.js";
 
 export class ClaudeHandler extends BaseAIHandler {
   constructor() {
-    super('claude', 'Anthropic Claude');
-    this.keyPool = new APIKeyPool('claude');
+    super("claude", "Anthropic Claude");
+    this.keyPool = new APIKeyPool("claude");
   }
 
   async review(code, problemContext) {
     const key = await this.keyPool.getNextKey();
-    if (!key) throw new Error('No Claude API key available.');
+    if (!key) throw new Error("No Claude API key available.");
 
     const settings = await Storage.getSettings();
-    const model = settings.aiModel || CONSTANTS.AI_PROVIDERS.claude.defaultModel;
+    const model =
+      settings.claude_model ||
+      settings.aiModel ||
+      CONSTANTS.AI_PROVIDERS.claude.defaultModel;
 
     const prompt = `Review this DSA solution for "${problemContext.title}". Language: ${problemContext.language}, Difficulty: ${problemContext.difficulty}. Code: \`${code}\`. Provide Time/Space complexity, optimizations, and key patterns.`;
 
     try {
-      const res = await fetch(`${CONSTANTS.AI_PROVIDERS.claude.endpoint}/messages`, {
-        method: 'POST',
-        headers: { 
-          'Content-Type': 'application/json',
-          'x-api-key': key,
-          'anthropic-version': '2023-06-01',
-          'anthropic-dangerously-allow-browser': 'true' // Caution: requires bg proxy or this header depending on exact extension env
+      const res = await fetch(
+        `${CONSTANTS.AI_PROVIDERS.claude.endpoint}/messages`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            "anthropic-dangerously-allow-browser": "true", // Caution: requires bg proxy or this header depending on exact extension env
+          },
+          body: JSON.stringify({
+            model,
+            max_tokens: 1024,
+            messages: [{ role: "user", content: prompt }],
+          }),
         },
-        body: JSON.stringify({
-          model,
-          max_tokens: 1024,
-          messages: [{ role: 'user', content: prompt }]
-        })
-      });
+      );
 
       if (!res.ok) {
         if (res.status === 429) this.keyPool.markFailed(key);
@@ -47,7 +53,7 @@ export class ClaudeHandler extends BaseAIHandler {
       const data = await res.json();
       return data.content[0].text;
     } catch (err) {
-      this.dbg.error('Claude review failed', err);
+      this.dbg.error("Claude review failed", err);
       throw err;
     }
   }