Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
Merge FASE 3: docs restructure into 8 subfolders
diegosouzapwafe2a67c7658
diff --cc docs/guides/ELECTRON_GUIDE.mdindex 0892a8f1d6,a9909eeb22..7da196f30a--- a/docs/guides/ELECTRON_GUIDE.md+++ b/docs/guides/ELECTRON_GUIDE.md@@@ -266,6 -264,6 +266,6 @@@ Releases are published to GitHub Releas## See Also- [SETUP_GUIDE.md](./SETUP_GUIDE.md)- - [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md)+ - [RELEASE_CHECKLIST.md](../ops/RELEASE_CHECKLIST.md)- Source: `electron/main.js`, `electron/preload.js`, `electron/package.json`-- Helpers: `scripts/prepare-electron-standalone.mjs`, `scripts/smoke-electron-packaged.mjs`+- Helpers: `scripts/build/prepare-electron-standalone.mjs`, `scripts/dev/smoke-electron-packaged.mjs`diff --cc scripts/check/check-env-doc-sync.mjsindex f68fea2eb7,0000000000..a69d0f94efmode 100644,000000..100644--- a/scripts/check/check-env-doc-sync.mjs+++ b/scripts/check/check-env-doc-sync.mjs@@@ -1,277 -1,0 +1,279 @@@+#!/usr/bin/env node+/**+ * Strict environment variable contract checker.+ *+ * Enforces that every env var referenced in OmniRoute source code appears in- * both `.env.example` and `docs/ENVIRONMENT.md`, and that the two files agree++ * both `.env.example` and `docs/reference/ENVIRONMENT.md`, and that the two files agree+ * on the documented var set. Falls back to a small allowlist for variables+ * that are intentionally documented but not literally referenced (legacy+ * aliases, future-supported hooks) or vice versa.+ *+ * Usage:+ * node scripts/check/check-env-doc-sync.mjs # strict (CI mode)+ * node scripts/check/check-env-doc-sync.mjs --lenient # legacy report-only mode+ *+ * Strict mode exits non-zero if any of these are non-empty:+ * - vars in code but missing from .env.example+ * - vars in .env.example but missing from ENVIRONMENT.md+ * - vars in ENVIRONMENT.md but missing from .env.example+ *+ * Programmatic API:+ * Other Node tests can `import { runEnvDocSync } from "./check-env-doc-sync.mjs"`+ * and pass `{ root, envExample, envDoc, codeVars, ignore, docOnlyAllowlist,+ * envOnlyAllowlist }` to drive the checker against fixtures.+ */++import fs from "node:fs";+import path from "node:path";+import { fileURLToPath } from "node:url";+import { execSync } from "node:child_process";++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = path.resolve(__dirname, "..", "..");++// ─── Allowlists ────────────────────────────────────────────────────────────+// Env vars referenced in code that should NOT trigger documentation drift.+// These are usually system/process vars or harness-only knobs.+const IGNORE_FROM_CODE = new Set([+ "NODE_ENV",+ "PATH",+ "HOME",+ "USER",+ "PWD",+ "SHELL",+ "TERM",+ "TZ",+ "LANG",+ "LC_ALL",+ "CI",+ "GITHUB_ACTIONS",+ "RUNNER_OS",+ // OS / Node internals frequently surfaced by indirect dependencies.+ "APPDATA",+ "LOCALAPPDATA",+ "XDG_CONFIG_HOME",+ "USERPROFILE",+ "PREFIX",+ // Next.js / Node test runners — these are framework-managed.+ "NEXT_DIST_DIR",+ "NEXT_PHASE",+ "NEXT_RUNTIME",+ "VITEST",+ // CI providers (set by the runner).+ "GITHUB_BASE_REF",+ "GITHUB_BASE_SHA",+ // Aliases for documented vars handled via fallback ordering.+ "API_KEY",+ "APP_URL",+ "PUBLIC_URL",+ "ANTHROPIC_API_URL",+ "OPENAI_API_URL",+ "LOG_LEVEL",+ // Internal QA helpers used only by scripts/ and Playwright.+ "QA_BASE_URL",+ "QA_LOCALES",+ "QA_REPORT_SUFFIX",+ "QA_ROUTES",+ // Doctor diagnostic flags (no runtime behavior yet — placeholders).+ "OMNIROUTE_DOCTOR_HOST",+ "OMNIROUTE_DOCTOR_LIVENESS_URL",+ "OMNIROUTE_PROVIDER_CATALOG_PATH",+ "OMNIROUTE_PROVIDER_TEST_MODEL",+ // Source typo / placeholder.+ "OMNIROUT",+ // Static config alias path (the canonical var is OMNIROUTE_PAYLOAD_RULES_PATH).+ "PAYLOAD_RULES_PATH",+]);++// Vars documented in ENVIRONMENT.md but intentionally absent from .env.example.+// Used for past-tense documentation (Audit / Dead vars section), legacy aliases+// with no runtime hook, and section anchors that look like vars to the regex.+const DOC_ONLY_ALLOWLIST = new Set([+ // Audit history (Removed / Dead Variables section).+ "CEREBRAS_API_KEY",+ "COHERE_API_KEY",+ "FIREWORKS_API_KEY",+ "GROQ_API_KEY",+ "MISTRAL_API_KEY",+ "NEBIUS_API_KEY",+ "PERPLEXITY_API_KEY",+ "TOGETHER_API_KEY",+ "XAI_API_KEY",+ "QIANFAN_API_KEY",+ "CURSOR_PROTOBUF_DEBUG",+ "CLI_COMPAT_KIRO",+ "CLI_KIMI_CODING_BIN",+ "CLI_ROO_BIN",+ "IFLOW_OAUTH_CLIENT_ID",+ "IFLOW_OAUTH_CLIENT_SECRET",+ // Source-code constants accidentally captured by the doc regex.+ "CLI_COMPAT_OMITTED_PROVIDER_IDS",+ // Sample default values that look like SHOUTY_NAMES (not env vars).+ "CHANGEME",+ // Legacy aliases — present in docs as "would be aliases" but read-only+ // through their canonical names today.+ "OMNIROUTE_CRYPT_KEY",+ "OMNIROUTE_API_KEY_BASE64",+ // Future-supported hooks: documented but currently hardcoded constants.+ "MAX_RETRY_INTERVAL_SEC",+ "REQUEST_RETRY",+ "SKILLS_EXECUTION_TIMEOUT_MS",+ "SKILLS_SANDBOX_DOCKER_IMAGE",+]);++// Vars present in .env.example but intentionally absent from ENVIRONMENT.md.+// Empty today — kept for forward compatibility / explicit exemption.+const ENV_ONLY_ALLOWLIST = new Set([]);++// ─── Parsing helpers ───────────────────────────────────────────────────────++/**+ * Extract VAR= entries from a `.env`-style file (handles commented examples).+ */+export function parseEnvExampleVars(text) {+ const vars = new Set();+ for (const line of String(text ?? "").split("\n")) {+ const m = line.match(/^#?\s*([A-Z][A-Z0-9_]+)\s*=/);+ if (m) vars.add(m[1]);+ }+ return vars;+}++/**+ * Extract `VARNAME` tokens from a markdown doc — matches anything in backticks+ * that looks like an env var (uppercase + digit + underscore).+ */+export function parseEnvDocVars(text) {+ const vars = new Set();+ for (const m of String(text ?? "").matchAll(/`([A-Z][A-Z0-9_]{2,})`/g)) {+ vars.add(m[1]);+ }+ return vars;+}++/**+ * Collect environment variable references in source code via grep against+ * the `process.env` member access pattern.+ */+function scanCodeVars({ cwd } = {}) {+ const repoRoot = cwd ?? REPO_ROOT;+ const stdout = execSync(+ "grep -rhoE 'process\\.env\\.[A-Z][A-Z0-9_]+' " ++ "src/ open-sse/ bin/ scripts/ electron/main.js electron/preload.js 2>/dev/null || true",+ { cwd: repoRoot, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 }+ );+ const vars = new Set();+ for (const line of stdout.split("\n")) {+ const m = line.match(/^process\.env\.([A-Z][A-Z0-9_]+)$/);+ if (m) vars.add(m[1]);+ }+ return vars;+}++/**+ * Diff helper.+ */+function diff(set, against) {+ return [...set].filter((v) => !against.has(v)).sort();+}++// ─── Programmatic entry point ──────────────────────────────────────────────++/**+ * Run the contract checker. All inputs are overridable for tests.+ *+ * Returns `{ ok: boolean, summary, problems: { codeMissingEnv, envMissingDoc,+ * docMissingEnv } }`.+ */+export function runEnvDocSync(options = {}) {+ const ignore = options.ignore ?? IGNORE_FROM_CODE;+ const docOnly = options.docOnlyAllowlist ?? DOC_ONLY_ALLOWLIST;+ const envOnly = options.envOnlyAllowlist ?? ENV_ONLY_ALLOWLIST;++ const envExampleText =+ options.envExampleText ??+ (options.envExamplePath+ ? fs.readFileSync(options.envExamplePath, "utf8")+ : fs.readFileSync(path.join(REPO_ROOT, ".env.example"), "utf8"));+ const envDocText =+ options.envDocText ??+ (options.envDocPath+ ? fs.readFileSync(options.envDocPath, "utf8")- : fs.readFileSync(path.join(REPO_ROOT, "docs", "ENVIRONMENT.md"), "utf8"));++ : fs.readFileSync(path.join(REPO_ROOT, "docs", "reference", "ENVIRONMENT.md"), "utf8"));++ const envVars = parseEnvExampleVars(envExampleText);+ const docVars = parseEnvDocVars(envDocText);++ const codeVars = new Set(+ [...(options.codeVars ?? scanCodeVars({ cwd: options.root }))].filter((v) => !ignore.has(v))+ );++ const codeMissingEnv = diff(codeVars, envVars);+ const envMissingDoc = diff(envVars, docVars).filter((v) => !envOnly.has(v));+ const docMissingEnv = diff(docVars, envVars).filter((v) => !docOnly.has(v));++ const ok =+ codeMissingEnv.length === 0 && envMissingDoc.length === 0 && docMissingEnv.length === 0;++ return {+ ok,+ summary: {+ code: codeVars.size,+ envExample: envVars.size,+ doc: docVars.size,+ },+ problems: {+ codeMissingEnv,+ envMissingDoc,+ docMissingEnv,+ },+ };+}++// ─── CLI ───────────────────────────────────────────────────────────────────++function printList(label, list, marker) {+ if (list.length === 0) {+ console.log(` ${marker || "✓"} ${label}: none`);+ return;+ }+ console.log(` ✗ ${label}: ${list.length}`);+ for (const v of list.slice(0, 50)) console.log(` - ${v}`);+ if (list.length > 50) console.log(` ... and ${list.length - 50} more`);+}++function main() {+ const lenient = process.argv.includes("--lenient");+ const result = runEnvDocSync();++ console.log("Env var contract sync report");+ console.log("============================");+ console.log(`Code references: ${result.summary.code} unique vars`);+ console.log(`In .env.example: ${result.summary.envExample} unique vars`);- console.log(`In docs/ENVIRONMENT.md: ${result.summary.doc} unique vars`);++ console.log(`In docs/reference/ENVIRONMENT.md: ${result.summary.doc} unique vars`);+ console.log();++ printList("In code but missing from .env.example", result.problems.codeMissingEnv);+ printList("In .env.example but missing from ENVIRONMENT.md", result.problems.envMissingDoc);+ printList("In ENVIRONMENT.md but missing from .env.example", result.problems.docMissingEnv);++ if (result.ok) {+ console.log("\n✓ Env / docs contract is in sync.");+ process.exit(0);+ }++ if (lenient) {+ console.log("\n⚠ Drift detected (lenient mode — exit 0).");+ process.exit(0);+ }+- console.log("\n✗ Env / docs contract is out of sync. Update .env.example, docs/ENVIRONMENT.md,");++ console.log(++ "\n✗ Env / docs contract is out of sync. Update .env.example, docs/reference/ENVIRONMENT.md,"++ );+ console.log(" or the allowlists in scripts/check/check-env-doc-sync.mjs and try again.");+ process.exit(1);+}++if (import.meta.url === `file://${process.argv[1]}`) {+ main();+}diff --cc scripts/docs/gen-provider-reference.tsindex 823d9f19d5,fcad51d1d8..39bdc09558--- a/scripts/docs/gen-provider-reference.ts+++ b/scripts/docs/gen-provider-reference.ts@@@ -1,6 -1,6 +1,6 @@@#!/usr/bin/env node- // Generates docs/PROVIDER_REFERENCE.md from src/shared/constants/providers.ts.+ // Generates docs/reference/PROVIDER_REFERENCE.md from src/shared/constants/providers.ts.-// Run: node --import tsx/esm scripts/gen-provider-reference.ts+// Run: node --import tsx/esm scripts/docs/gen-provider-reference.tsimport fs from "node:fs";import path from "node:path";@@@ -22,11 -22,11 +22,11 @@@ importVIDEO_PROVIDER_IDS,EMBEDDING_RERANK_PROVIDER_IDS,SELF_HOSTED_CHAT_PROVIDER_IDS,-} from "../src/shared/constants/providers.ts";+} from "../../src/shared/constants/providers.ts";const __dirname = path.dirname(fileURLToPath(import.meta.url));-const ROOT = path.resolve(__dirname, "..");+const ROOT = path.resolve(__dirname, "..", "..");- const OUT_FILE = path.join(ROOT, "docs", "PROVIDER_REFERENCE.md");+ const OUT_FILE = path.join(ROOT, "docs", "reference", "PROVIDER_REFERENCE.md");type ProviderRecord = {id: string;diff --cc scripts/docs/generate-docs-index.mjsindex 85015cea42,f4d9f861b9..24a83c1ef9--- a/scripts/docs/generate-docs-index.mjs+++ b/scripts/docs/generate-docs-index.mjs@@@ -5,8 -5,11 +5,11 @@@* src/app/docs/lib/docs-auto-generated.ts with static navigation + search data.** This file is imported by both client and server components — NO fs/path imports.- * Run via: node scripts/generate-docs-index.mjs+ * Run via: node scripts/docs/generate-docs-index.mjs* Automatically runs as prebuild step.+ *+ * Sections come from the on-disk subfolder layout introduced in FASE 3 of the+ * platform overhaul. Order is fixed by SECTION_ORDER below.*/import fs from "node:fs";