Adds scripts/i18n/run-translation.mjs — the new docs translation pipeline.
Reads sources from CLAUDE.md, GEMINI.md, AGENTS.md, CONTRIBUTING.md, SECURITY.md,
CODE_OF_CONDUCT.md, README.md at the repo root, plus all .md files under
docs/<subfolder>/ (recursing one level). Writes targets to
docs/i18n/<locale>/<source-path>.
Behavior:
- SHA-256 hash per source + per target stored in .i18n-state.json
- Re-runs only retranslate sources whose hash changed (or whose target file
is missing)
- Excludes docs/i18n/, docs/screenshots/, docs/superpowers/, docs/diagrams/,
docs/reports/ subtrees + I18N.md and README.md filenames
- Backend reads OMNIROUTE_TRANSLATION_* env vars (URL, API key, model,
timeout, concurrency); never logs the API key
- Chunks markdown on top-level ## headings before sending to the LLM
- Pre-formats translator output with Prettier so lint-staged commit hooks
cannot mutate file content out from under the hash registry
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds config/i18n.json (41 locales) + JSON-Schema as the single source of
truth for the locale list, RTL set, and docs-translation policy. This file
is consumed by:
- The runtime UI config in src/i18n/config.ts (next commit).
- The docs translation pipeline (scripts/i18n/run-translation.mjs, added in
a later commit).
- The drift checker (scripts/i18n/check-translation-drift.mjs).
Fields:
- default: source locale (en)
- rtl: locale codes rendered right-to-left
- uiOnly: locales shipped in UI but not target of docs translation
- docsExcluded: locales NOT receiving docs translations (source language)
- locales[]: code, label, name, native, english, flag
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
FASE 1 moved scripts/sync-env.mjs to scripts/dev/sync-env.mjs. The implementation
(src/lib/system/autoUpdate.ts) was updated, but two test assertions still referenced
the old path. Updates the regex matchers to the new path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolves two conflicts:
- docs/diagrams/README.md: FASE 3 created a placeholder, FASE 4 created the
canonical content. Adopts FASE 4 content and updates the doc paths to the
FASE 3 subfolder layout (architecture/, frameworks/, routing/, guides/).
- package.json: combined FASE 1's new scripts/build/ and scripts/check/ paths
with FASE 4's new docs:render-diagrams script.
Post-merge fixes:
- Rewrites diagram link paths in the 7 subfolder docs from ./diagrams/X to
../diagrams/X (FASE 4 added flat-layout links before FASE 3's subfolder move).
- Adds the i18n-flow diagram link to docs/guides/I18N.md (auto-merge missed it).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reorganizes /docs into 8 subfolders (architecture, guides, reference, frameworks,
routing, security, compression, ops). Resolves two conflicts:
- scripts/docs/gen-provider-reference.ts: combined FASE 1's new __dirname-based
ROOT (two levels up from scripts/docs/) with FASE 3's new output path
(docs/reference/PROVIDER_REFERENCE.md).
- scripts/check-env-doc-sync.mjs: deleted by FASE 1, modified by FASE 3; FASE 1's
delete wins (file is at scripts/check/ now). The FASE 3 intent (point to
docs/reference/ENVIRONMENT.md) was applied to the strict checker at the new path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolves conflict in scripts/check/check-env-doc-sync.mjs (FASE 1 moved it from scripts/ to scripts/check/, FASE 2 modified it at the old path). Applies FASE 2's strict checker version at the new path, fixes __dirname-based REPO_ROOT to traverse two levels up, and updates the unit test import to the new path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add scripts/docs/render-diagrams.mjs as a thin wrapper around
@mermaid-js/mermaid-cli (mmdc):
- Renders every docs/diagrams/*.mmd into docs/diagrams/exported/*.svg
- Writes a Puppeteer config with --no-sandbox for Ubuntu 23.10+/WSL
- Exits non-zero on first failure so CI can gate on rendering
Expose it as `npm run docs:render-diagrams` and commit the initial
8 rendered SVGs so reviewers see the diagrams without having to install
the renderer locally.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Regenerate the auto-generated docs index after the docs restructure
and remove repository-local audit, PR metadata, and ad hoc test files
that should not be kept in source control
For all 40 locales, move docs/i18n/<lang>/docs/<DOC>.md into the matching
subfolder (architecture/, guides/, reference/, ...). Mirror references in
docs/i18n/<lang>/{llm.txt,CHANGELOG.md,CONTRIBUTING.md,README.md} are also
rewritten to the new paths so the i18n llm.txt mirror check stays byte-equal
to the root llm.txt body.
These are mechanical moves only — actual translations remain unchanged and
will be regenerated incrementally in FASE 5 (hash-based pipeline).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- src/app/docs/lib/docs-auto-generated.ts is regenerated from docs/<sub>/ with
fileName values like "architecture/ARCHITECTURE.md". The dynamic slug page
joins these against process.cwd()/docs so resolution still works.
- src/app/api/openapi/spec/route.ts now looks for the spec at
docs/reference/openapi.yaml first, with the flat-path fallback retained for
older bundles.
- tests updated: integration-wiring expects docs/reference/{API_REFERENCE.md,
openapi.yaml}; docs-site-overhaul reflects the new 8-section nav titles
(Architecture, Guides, Reference, Frameworks, Routing, Security, Compression,
Ops) and the new section for setup-guide ("Guides").
- open-sse/mcp-server/README.md picks up the rewritten docs/ reference.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Update tooling for the new docs/<subfolder>/ layout:
- scripts/generate-docs-index.mjs walks the 8 subfolders in defined order and
emits fileName values relative to docs/ (e.g. "architecture/ARCHITECTURE.md").
- scripts/check-docs-sync.mjs reads docs/reference/openapi.yaml.
- scripts/check-docs-counts-sync.mjs targets new doc paths.
- scripts/check-env-doc-sync.mjs reads docs/reference/ENVIRONMENT.md.
- scripts/gen-provider-reference.ts writes to docs/reference/PROVIDER_REFERENCE.md.
- scripts/pack-artifact-policy.ts allowlists docs/reference/openapi.yaml.
- New scripts/docs/{fix-internal-links,move-i18n-mirrors}.mjs are one-shot
FASE 3 helpers, safe to delete after merge.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrite `docs/<DOC>.md` references in README, CLAUDE.md, AGENTS.md, GEMINI.md,
CONTRIBUTING.md, SECURITY.md, llm.txt, CHANGELOG.md, Tuto_Qdrant.md and the
.agents/.claude skill+workflow definitions to use the new subfolder layout
(e.g. docs/architecture/ARCHITECTURE.md, docs/routing/AUTO-COMBO.md).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group docs into intent-based subfolders so the topic each file covers is visible
from the directory layout: architecture/, guides/, reference/, frameworks/,
routing/, security/, compression/, ops/. Adds an empty diagrams/ placeholder
(populated in FASE 4) and a navigable docs/README.md index. Files were moved
with git mv so history is preserved. Internal cross-doc links were rewritten
to point at the new subfolder paths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrites scripts/check-env-doc-sync.mjs so the default mode is strict
(non-zero exit on drift between code references, .env.example, and
docs/ENVIRONMENT.md). The previous "report-only" behavior is still
available via --lenient for ad-hoc local diagnostics.
Highlights:
- Strict mode fails when any of these three sets is non-empty:
1. process.env vars referenced in src/, open-sse/, bin/, scripts/,
electron/main.js, electron/preload.js but missing from
.env.example.
2. .env.example vars missing from docs/ENVIRONMENT.md.
3. docs/ENVIRONMENT.md vars missing from .env.example.
- Allowlists are explicit and curated:
* `IGNORE_FROM_CODE` — system vars (NODE_ENV, PATH, ...), Next.js
internals, CI runner injections, doctor placeholders, and aliases
handled by fallback ordering.
* `DOC_ONLY_ALLOWLIST` — vars intentionally documented in
ENVIRONMENT.md but absent from .env.example (Audit section,
legacy aliases, future-supported hooks, `CHANGEME` default value).
* `ENV_ONLY_ALLOWLIST` — reserved for future use; currently empty.
- The checker now exposes a programmatic `runEnvDocSync({ envExampleText,
envDocText, codeVars, ignore, docOnlyAllowlist, envOnlyAllowlist })`
entry point that other Node tests can import without touching disk.
Helpers `parseEnvExampleVars` and `parseEnvDocVars` are exported so
fixtures can validate the regex contract.
Test coverage in tests/unit/check-env-doc-sync.test.ts (13 cases):
- Parses env.example assignments (commented and uncommented), rejects
prose, and rejects backtick literals that aren't SHOUTY env names.
- Drives runEnvDocSync against in-memory fixtures for every drift
direction (code-missing-env, env-missing-doc, doc-missing-env) and
asserts the allowlists / ignore set behave as expected.
- Calls runEnvDocSync() with no overrides to assert the live
.env.example, docs/ENVIRONMENT.md and source-code references stay in
sync. This is the same check that runs in pre-commit / CI, so the
unit-test failure surfaces drift before reviewers do.
.env.example: documents `AWS_REGION` and `AWS_DEFAULT_REGION` so
Bedrock/Kiro/audio-speech callers stay in the contract.
docs/ENVIRONMENT.md: adds rows for AWS_REGION / AWS_DEFAULT_REGION
inside §20 Provider-Specific Settings.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings docs/ENVIRONMENT.md in line with the cleaned-up .env.example. Every
variable present in .env.example now has a row in ENVIRONMENT.md, and the
formatting convention used by the doc tables matches the regex used by
scripts/check-env-doc-sync.mjs.
Notable additions, per section:
- §3 Network & Ports — HOST, HOSTNAME bind overrides.
- §6 Tool & Routing Policies — OMNIROUTE_PAYLOAD_RULES_PATH,
OMNIROUTE_PAYLOAD_RULES_RELOAD_MS.
- §7 URLs & Cloud Sync — KIE_CALLBACK_URL, OMNIROUTE_KIE_CALLBACK_URL,
OMNIROUTE_PUBLIC_URL, plus the three new quota endpoint overrides
(OMNIROUTE_CROF_USAGE_URL, OMNIROUTE_GEMINI_CLI_USAGE_URL,
OMNIROUTE_CODEWHISPERER_BASE_URL).
- §9 CLI Tool Integration — CLI_QWEN_BIN.
- §10 Internal Agent & MCP — MCP description compression toggles,
background-task and healthcheck overrides, RTK trust flag, Redis auth
cache toggle, ANTIGRAVITY_CREDITS.
- §11 OAuth — GitLab legacy fallback variables (`GITLAB_BASE_URL`,
`GITLAB_OAUTH_CLIENT_ID`, `GITLAB_OAUTH_CLIENT_SECRET`).
- §13 CLI Fingerprint — Kimi identity overrides + CLI_COMPAT_* table
reshaped so the variable names appear in their own backticks (matches
the env-doc sync regex). Removed the orphaned CLI_COMPAT_KIRO row.
- §14 API Key Providers — pruned the stub rows for providers whose
static *_API_KEY is no longer consumed at runtime. Added an audit
note pointing to the bottom of the doc.
- §15 Timeout Settings — OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS,
OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS/GRACE_MS, and the
OMNIROUTE_CIRCUIT_BREAKER_* table.
- §16 Logging — APP_LOG_ROTATION_CHECK_INTERVAL_MS and the
CHAT_LOG_* / CHAT_DEBUG_FILE knobs.
- §21 Proxy Health — RATE_LIMIT_AUTO_ENABLE force-on/off documentation,
HEALTHCHECK_STAGGER_MS.
- §22 Debugging — Cursor executor toggles (CURSOR_DEBUG /
CURSOR_STREAM_DEBUG / CURSOR_DUMP_FILE / CURSOR_STREAM_TIMEOUT_MS /
CURSOR_STATE_DB_PATH / CURSOR_TOKEN), OMNIROUTE_LOG_REQUEST_SHAPE.
Removed CURSOR_PROTOBUF_DEBUG (orphan).
- §23 GitHub — generic GITHUB_TOKEN fallback.
- New §25 — Provider quotas, tunnels, backups & misc runtime, covering
Alibaba Bailian overrides, model alias compatibility, context reserve,
MITM debug proxy, the 1Proxy egress pool, Tailscale binaries, ngrok,
DB backups, and OMNIROUTE_TLS_PROXY_URL. Also documents REDIS_URL,
which previously lived only in .env.example.
- New §26 — Test & E2E harness: OMNIROUTE_E2E_BOOTSTRAP_MODE,
OMNIROUTE_E2E_PASSWORD, healthcheck disablers, Playwright skip-build,
uninstall-hook skip, ecosystem wait timeout, all ELECTRON_SMOKE_*
variables, CLI_DEVIN_BIN.
The Audit section is updated with the v3.8.0 removals (provider API key
stubs, CURSOR_PROTOBUF_DEBUG, CLI_COMPAT_KIRO, QIANFAN_API_KEY) and a
prominent note at the top of the doc explains the sync contract.
.env.example: documents OUTBOUND_SSRF_GUARD_ENABLED (legacy SSRF guard
flag actually consumed by src/shared/network/outboundUrlGuard.ts) and
CODEX_CLIENT_VERSION override.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Centralizes a handful of hardcoded URLs, fetch timeouts, and circuit-breaker
constants behind opt-in environment variables. Behavior is unchanged when
the variables are unset because every call site keeps its current default.
- open-sse/services/usage.ts: extracts CROF_USAGE_URL,
GEMINI_CLI_USAGE_URL, CODEWHISPERER_BASE_URL constants backed by
OMNIROUTE_CROF_USAGE_URL, OMNIROUTE_GEMINI_CLI_USAGE_URL, and
OMNIROUTE_CODEWHISPERER_BASE_URL. Lets operators redirect quota probes
through corporate mirrors or a test fixture.
- open-sse/config/constants.ts: PROVIDER_PROFILES circuit-breaker
thresholds and reset timeouts now honor OMNIROUTE_CIRCUIT_BREAKER_*
env vars (oauth/api-key/local) with the same defaults as before.
- src/shared/utils/fetchTimeout.ts: DEFAULT_TIMEOUT_MS reads
OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS (fallback 120000) so deployments can
raise the global fallback without changing FETCH_TIMEOUT_MS semantics.
- open-sse/services/chatgptTlsClient.ts: DEFAULT_TIMEOUT_MS and
HARD_TIMEOUT_GRACE_MS now honor OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS and
OMNIROUTE_CHATGPT_TLS_GRACE_MS (defaults 60000 / 10000).
- .env.example: documents the 11 new variables in the URLs and TIMEOUT
sections.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Removes 11 environment variable entries from `.env.example` that no
longer correspond to any reference in source code:
- Provider API keys with no runtime hook today: CEREBRAS_API_KEY,
NEBIUS_API_KEY, PERPLEXITY_API_KEY, MISTRAL_API_KEY, COHERE_API_KEY,
TOGETHER_API_KEY, GROQ_API_KEY, XAI_API_KEY, FIREWORKS_API_KEY.
Provider credentials are managed via Dashboard/Providers or the
encrypted DB; the leftover entries were stubs only.
- CURSOR_PROTOBUF_DEBUG (executor uses CURSOR_DEBUG/CURSOR_STREAM_DEBUG).
- CLI_COMPAT_KIRO (Kiro is in CLI_COMPAT_OMITTED_PROVIDER_IDS).
Kept four entries from the original audit list because they are still
exercised at runtime (verified via grep on docker-compose and dynamic
`${PROVIDER}_USER_AGENT` lookup in BaseExecutor):
- ANTIGRAVITY_USER_AGENT (dynamic in BaseExecutor.buildHeaders)
- KIRO_USER_AGENT (same dynamic pattern)
- PROD_API_PORT, PROD_DASHBOARD_PORT (docker-compose.prod.yml)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Removes 23 obsolete one-shot scripts under scripts/scratch/ and the
top-level scripts/scratch.mjs. Their history is preserved in the
archive/scripts-scratch-pre-3.8 branch for reference.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
REPOSITORY_MAP.md (new, ~26 KB) documents every directory and root file
with one-line descriptions so newcomers can navigate the tree without
opening files. Covers src/, open-sse/, electron/, bin/, scripts/, docs/,
tests/, .github/, .husky/, .claude/, .agents/, and the underscore-prefixed
out-of-tree directories.
README.md (was ~100 KB / 1876 lines) is rewritten as a sales-focused
landing of ~22 KB / 482 lines:
- Updated SEO/JSON-LD/FAQ to v3.8.0 (was 3.7.8) with correct counts
(177 providers, 14 strategies, 37 MCP tools, 14 OAuth, 9-factor Auto-Combo).
- Trimmed long FAQ/Troubleshooting/Compression Math/Docker prose
in favor of links to the dedicated docs.
- Added "What's new in v3.8.0" section + competitive comparison table.
- Added a categorized Documentation index covering all 44 docs in docs/.
- Kept screenshots, quick start, providers summary, compatibility tables,
multi-platform install table, use-cases at a glance, i18n strip,
community + security blocks.
The CHANGELOG, deep technical guides, and per-area references stay where
they belong — under docs/. The README is now a marketing page that
points to them.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds three automated drift-detection scripts under scripts/, plus npm
helpers to run them, and applies small follow-ups to TERMUX, I18N, and
CODEBASE docs flagged by the docs audit.
New scripts (scripts/):
- check-env-doc-sync.mjs — cross-checks process.env.X in code vs
.env.example vs docs/ENVIRONMENT.md. Soft-fails by default; --strict
exits 1 on drift.
- check-docs-counts-sync.mjs — validates counts (executors, routing
strategies, OAuth providers, A2A skills, cloud agents) match between
code and docs.
- check-deprecated-versions.mjs — flags hardcoded stale versions and
"Last updated" dates older than 60 days. Uses hardcoded regexes to
satisfy semgrep ReDoS guidance.
package.json:
- New scripts: check:env-doc-sync, check:docs-counts,
check:deprecated-versions, check:docs-all (umbrella).
Doc refinements:
- TERMUX_GUIDE: spell out the Node version range required by package.json.
- I18N: note that docs/i18n/in/ tree is an orphan duplicate of hi/ that
the generator no longer writes to; replace hard-coded
UNTRANSLATABLE_KEYS count with "varies per release".
- CODEBASE_DOCUMENTATION: minor wording.
Pre-commit hook is unchanged — the new checks are heuristic and ship as
on-demand npm scripts to avoid false-positive blocks.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Refresh the documentation set for v3.8.0 with new guides covering
authz, agent protocols, cloud agents, compliance, electron, evals,
guardrails, memory, skills, stealth, tunnels, webhooks, and more.
Add an auto-generated provider reference plus a
`gen:provider-reference` script to keep provider catalog docs aligned
with `src/shared/constants/providers.ts`.
Refresh the v3.8.0 documentation set across API, setup, Docker,
environment, Fly.io, VM deployment, and troubleshooting guides.
Document the updated budget payload, management-auth requirements,
WebSocket bridge secret, Compose profiles, production deployment
details, and expanded Node support. Also update the OpenAPI catalog,
raise coverage thresholds to match the current baseline, and align
cloud-agent task route typing and schemas with the stricter runtime
behavior.
Centralize optional API key capability checks so dashboard forms and
provider schemas share the same rules, including keyless Pollinations
support and cloud-agent batch testing mode.
Also align auto-combo config on `routerStrategy`, keep legacy combo
reads compatible, preserve MCP routes as management APIs, narrow
`require-login` public access to readonly/bootstrap flows, and make
cloud-agent CORS reflect the request origin for credentialed requests.
Protect cloud agent task routes and model cooldown management endpoints
with management-session auth and consistent CORS handling.
Also align cloud agent API serialization with the dashboard, reuse the
provider connection schema for CLI key storage, and accept active OAuth
tokens when building virtual auto-combo candidates.
Integrated into release/v3.8.0 after syncing the contributor branch, removing unrelated workflow/package-lock changes, and validating Command Code provider, auth, validation, and Responses coverage locally.
Integrated into release/v3.8.0 after syncing the contributor branch, removing unrelated workflow/docker/package-lock changes, and validating provider-scoped models coverage locally.
Integrated into release/v3.8.0 after syncing the contributor branch, removing unrelated dependency churn, and validating executor/default URL coverage locally.
