Wires the new platform-overhaul gates into the Detailed Checklist used by
the release-cut workflow:
Documentation block:
npm run check:docs-all (umbrella over sync, counts, env-doc, deprecated, doc-links)
npm run check:env-doc-sync (code ↔ .env.example ↔ ENVIRONMENT.md parity)
npm run check:doc-links (no broken internal markdown refs)
i18n block (replaces stale `scripts/i18n-check.mjs` mention):
npm run i18n:check (drift between source docs and .i18n-state.json)
npm run i18n:check-ui-coverage (every locale ≥ 80% UI key coverage)
npm run i18n:sync-ui:dry (0 missing keys across 40 locales)
Note about running npm run i18n:run when source English docs change.
These are the same checks newly enforced by the docs-sync-strict and
i18n-ui-coverage CI jobs added in commit acf6b93d.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds an Unreleased entry summarizing the nine-phase platform overhaul that
ships in v3.8.x: scripts cleanup, .env audit, /docs subfolder restructure,
diagrams folder, hash-based docs translation pipeline, UI key sync,
/src/app/docs drift fixes + frontmatter + openapi feed, and the new CI
gates (env-doc-sync strict, doc-links, docs-sync-strict workflow,
i18n-ui-coverage workflow). Also records the Fixed entry for the 270
broken-link sweep.
No version bump — that is intentionally left for the release-cut workflow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The FASE 7 frontmatter sync touched docs/architecture/ARCHITECTURE.md but
.i18n-state.json was not refreshed, so npm run i18n:check reported
source-changed drift on every subsequent run.
Resolution: re-ran the hash-based translator end-to-end (npm run i18n:run
-- --locale=pt-BR --files=docs/architecture/ARCHITECTURE.md) which:
- retranslated the source through the production backend (14 chunks,
75 KB pt-BR output);
- persisted the new source/target SHA-256 pair in .i18n-state.json
(target_hash now matches the regenerated translation);
- left every other source/locale pair untouched.
After the run:
npm run i18n:check → PASS - all sources and targets match recorded hashes.
The pre-commit i18n drift advisory will no longer warn for this file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The FASE 3 /docs restructure moved files into 8 subfolders (architecture,
guides, reference, frameworks, routing, security, compression, ops) but left
several link categories with stale relative paths. The new check:doc-links
gate (FASE 8) surfaced these and produced this exhaustive fix sweep.
Categories repaired (counts before → after, total broken: 270 → 0):
i18n-relative (241 → 0): docs in subfolders now reference translations
under docs/i18n/<locale>/docs/<subfolder>/<FILE>.md (one extra "../"
plus the docs/<subfolder>/ segment). Affects ARCHITECTURE, FEATURES,
USER_GUIDE, TROUBLESHOOTING, UNINSTALL, VM_DEPLOYMENT_GUIDE,
API_REFERENCE, and the I18N.md self-reference table.
parent-relative (14 → 0): refs like ../CLAUDE.md, ../CONTRIBUTING.md,
../AGENTS.md, ../Tuto_Qdrant.md, ../open-sse/..., ../electron/...,
../src/... promoted from one to two parent hops (../ → ../../) to
reach repo root from docs/<subfolder>/.
screenshots (9 → 0): FEATURES.md PNG refs rewritten to ../screenshots/
(assets live at docs/screenshots/ unchanged).
missing-rfc (2 → 0): RFC-AUTO-ASSESSMENT.md was deleted earlier in the
overhaul; replaced refs in EVALS.md with pointers to the live
AUTO-COMBO.md scoring doc plus an in-prose mention of
src/domain/assessment/.
other (4 → 0): ENVIRONMENT.md → ../../.env.example,
SETUP_GUIDE.md → ../../{open-sse/mcp-server,src/lib/a2a}/README.md,
PROVIDER_REFERENCE.md → ../../src/shared/... and ../../open-sse/...,
VM_DEPLOYMENT_GUIDE.md omnirouteCloud reference replaced with a
pointer to in-repo TUNNELS_GUIDE.md (omnirouteCloud lives in a
separate companion repo).
Validation:
npm run check:doc-links → PASS (501 internal links, 0 broken)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds two strict drift gates that mirror (and harden) the new pre-commit
advisories from FASE 8:
- docs-sync-strict: runs `npm run check:docs-all` (docs version sync,
counts, env-doc contract, deprecated versions, and the new internal
doc-links checker) plus the i18n translation-drift check in strict
mode.
- i18n-ui-coverage: enforces ≥80% UI message coverage across every
configured locale.
Both jobs slot in immediately after `lint`, reusing the existing
setup-node@v6 + cache pattern. They are also wired into ci-summary
(`needs` + dashboard table) so the dashboard surfaces their status.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pre-commit now runs three additional drift checks beyond the existing
docs-sync + any-budget gates:
1. check-env-doc-sync (strict) — blocks commits that drift the env
contract across code, .env.example, and ENVIRONMENT.md.
2. check-translation-drift --warn — advisory only; prints a hint when
docs/i18n mirrors are stale so devs can run `npm run i18n:run`
before pushing. CI enforces strict mode in the new gate.
3. check-ui-keys-coverage --threshold=80 — pre-commit prints a hint
when any locale dips below 80%, but does not block. CI enforces
strict mode.
End-to-end pre-commit duration: ~28s on a clean tree (40 locales).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Expose `npm run check:doc-links` and add it to the end of `check:docs-all`
so the new internal-link gate runs alongside the other documentation
sync checks. Pre-existing broken links (272) will be tracked and fixed
under FASE 9; the CI strict gate added in this phase makes the debt
visible without blocking pre-commit (which still runs only check:docs-sync).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds scripts/check/check-doc-links.mjs that scans every docs/**/*.md
(excluding i18n mirrors, screenshots, exported diagrams, and superpowers
plans) and verifies that every internal markdown/HTML link resolves to a
file on disk. External URLs (http/https/mailto/tel), anchor-only links,
and fenced code blocks are ignored.
Supports --report (informational, exit 0), --json (machine-readable),
and --help. Default mode exits 1 when any broken link is found, so this
can be wired as a CI gate. Initial baseline reveals ~270 pre-existing
broken links carried over from prior reorgs (i18n relative paths,
removed RFC drafts, stale screenshot refs) that FASE 9 will clean up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- scripts/docs/gen-openapi-module.mjs (new): build helper that loads
docs/reference/openapi.yaml via js-yaml, flattens paths × methods, and
emits src/app/docs/lib/openapi.generated.ts with strongly-typed
OPENAPI_ENDPOINTS, OPENAPI_TAGS, OPENAPI_VERSION, OPENAPI_TITLE plus
the OpenApiEndpoint interface (no `any`, deterministic ordering).
By default it skips internal management paths (anything under /api/
that isn't /api/v1/*) so the Api Explorer focuses on the OpenAI-
compatible public surface — 19 endpoints for v3.8.0 (Chat, Messages,
Responses, Embeddings, Images, Audio, Moderations, Rerank, Models,
System). Add --include-management to emit all 121 paths if needed.
- src/app/docs/components/ApiExplorerClient.tsx: drop the 13-entry
hardcoded API_ENDPOINTS array; the component now imports from
@/app/docs/lib/openapi.generated. Tags come from the spec; the
"Try It" form picks an example body keyed by full path (8 well-known
bodies pre-seeded, everything else starts empty). The header pill
now shows endpoint count + OpenAPI version, and an "auth" pill is
rendered next to operations whose spec declares non-empty security.
- package.json: prebuild:docs now chains gen-openapi-module after the
docs index generator so `next build` always sees a fresh module.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every .md under docs/{architecture,guides,reference,frameworks,routing,
security,compression,ops,diagrams} plus docs/README.md now opens with:
---
title: "<inferred from first H1>"
version: 3.8.0
lastUpdated: 2026-05-13
---
46 files updated (no docs were skipped — none had pre-existing
frontmatter). [slug]/page.tsx already reads frontmatter.version and
frontmatter.lastUpdated via gray-matter and renders a "v3.8.0" pill
plus a "Last updated" caption, so the UI picks these up automatically.
Helper: scripts/docs/add-frontmatter.mjs — idempotent (skips files that
already start with `---`), falls back to a humanized basename when no
leading H1 exists. Excludes docs/i18n/, docs/screenshots/,
docs/superpowers/, docs/diagrams/exported/. Re-runnable safely.
Also regenerated src/app/docs/lib/docs-auto-generated.ts: 44 docs across
8 sections (Architecture / Guides / Reference / Frameworks / Routing /
Security / Compression / Ops), which now includes the 14 docs that were
missing from the v3.7 sidebar (Cloud Agents, Guardrails, Memory, Skills,
Webhooks, Evals, Authz, Agent Protocols, Repository Map, Provider
Reference, Reasoning Replay, Stealth Guide, Tunnels Guide, Electron
Guide).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- ARCHITECTURE.md and CODEBASE_DOCUMENTATION.md: 179 → 177 registered
providers (canonical from src/shared/constants/providers.ts).
- FEATURES.md and en.json wizard step: 13 → 14 routing strategies; lists
all 14 explicitly including reset-aware (the missing one).
- llm.txt root: combo strategy count corrected in 3 places (UI tree,
dashboard summary, fallback semantics).
- MCP-SERVER.md: 37 tool count was already correct; added a "Related
Frameworks (v3.8.0)" section pointing to Cloud Agents
(docs/frameworks/CLOUD_AGENT.md) and Guardrails
(docs/security/GUARDRAILS.md), both sibling frameworks intentionally
outside the MCP tool catalog.
- scripts/i18n/sync-llm-mirrors.mjs (new): idempotent helper to push
root llm.txt body into the 40 docs/i18n/<locale>/llm.txt mirrors
while preserving each locale's heading + language bar prefix; ran
it to refresh all 40 mirrors so `check:docs-sync` is green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reads the current request locale via `getLocale()` from next-intl and
prefers a translated markdown copy under
`docs/i18n/<locale>/docs/<fileName>` when one exists. Falls back to
the English source otherwise, so locales with partial coverage stay
readable instead of 404ing.
Path resolution is hardened: every read is resolved against an
absolute docs root and verified to live inside it, so a stray
filename in the docs index cannot escape the directory.
This is the runtime counterpart to the DocsI18n removal: the locale
preference set by the shared LanguageSelector in the docs layout now
materially affects what content the page renders.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The cosmetic DocsI18n.tsx shim duplicated the locale catalog that
already lives in config/i18n.json and consumed it through a separate
client hook (useDocsLocale + a 10-entry hard-coded SECTION_LABELS
map). It only ever translated sidebar section titles — the docs
content itself was always English.
Now the /docs page uses the same `LanguageSelector` component as the
rest of the dashboard, backed by next-intl + config/i18n.json. The
locale cookie set there is consumed by the [slug] page server
component (next commit) to actually serve translated markdown.
Removed:
- src/app/docs/components/DocsI18n.tsx (203 lines)
Updated:
- src/app/docs/layout.tsx — swaps DocsLocaleSwitcher for the shared
LanguageSelector
- tests/unit/docs-site-overhaul.test.ts — replaces the DocsI18n
importability assertions with checks that (a) the shared next-intl
config covers the same locales, (b) the global LanguageSelector
is the new docs switcher, and (c) the DocsI18n module is gone.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ran `npm run i18n:sync-ui` against every non-English locale to
replicate the full key tree from `src/i18n/messages/en.json`. Missing
strings now show up as `__MISSING__:<english_value>` placeholders,
which:
- keep the catalogs the same shape as the source-of-truth, so a
runtime `useTranslations('feature.x')` call no longer falls back
to the English bundle for every drifted key;
- are visible to reviewers (and to the optional `--translate-markers`
pass in sync-ui-keys.mjs) so the drift can be paid down
incrementally.
Volume summary (40 locales):
- 25,234 placeholders inserted in total
- zh-CN closest to parity (+105)
- most European/Asian locales (+710)
- pt-BR slightly ahead (+589)
- bn/fa/gu/in/mr/sw/ta/te/ur (+445)
No existing translated strings were touched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New script `scripts/i18n/check-ui-keys-coverage.mjs` compares every
`src/i18n/messages/<locale>.json` against `en.json` and reports
per-locale coverage: missing keys, __MISSING__ placeholder counts,
and real translated coverage percentage.
Modes:
- default: fail with exit 1 if any locale falls below `--threshold`
(default 80%)
- `--report`: print the same table but always exit 0 (informational)
- `--json`: machine-readable output for CI dashboards
Wired into `i18n:check-ui-coverage` npm script (added in the previous
commit). FASE 8 will decide whether to make this a pre-push gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New script `scripts/i18n/sync-ui-keys.mjs` replicates keys present in
`src/i18n/messages/en.json` into every other locale catalog, marking
missing strings with a `__MISSING__:<english_value>` sentinel so the
drift is auditable and recoverable.
The script also accepts `--translate-markers` to call the OmniRoute
translation backend (same env vars as run-translation.mjs) and replace
those placeholders with real translations. Bounded concurrency, fail-
fast on missing env vars, and a `--dry-run` mode mirror the existing
docs translation pipeline.
Adds the matching `i18n:sync-ui` / `i18n:sync-ui:dry` npm scripts and
`i18n:check-ui-coverage` (next commit) wiring placeholder so the JSON
files can be backfilled with `npm run i18n:sync-ui`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a tiny built-in dotenv loader at the top of run-translation.mjs that
parses the repo-root .env file into process.env (without pulling dotenv
as a dependency). Existing process.env values still take precedence, so
shell/CI overrides keep working.
Before: `npm run i18n:run` failed with "Missing required env var:
OMNIROUTE_TRANSLATION_API_URL" unless the operator exported the vars in
the current shell.
After: the npm scripts (i18n:run, i18n:run:dry) pick up .env automatically.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds OMNIROUTE_TRANSLATION_API_URL, OMNIROUTE_TRANSLATION_API_KEY,
OMNIROUTE_TRANSLATION_MODEL, OMNIROUTE_TRANSLATION_TIMEOUT_MS, and
OMNIROUTE_TRANSLATION_CONCURRENCY to both .env.example (commented placeholders)
and docs/reference/ENVIRONMENT.md (new 'Docs translation pipeline' subsection).
Restores the env-doc-sync contract reported by the strict checker added in
FASE 2 — these vars are now referenced by scripts/i18n/run-translation.mjs
introduced in this branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates docs/guides/I18N.md with a 'Translation pipeline (recommended)' section
documenting the npm run i18n:run / :check / :run:dry flow, required env vars,
state file semantics, and the legacy-script deprecation notice. The legacy
Quick-Reference row for the Python translator is replaced with the new npm
script entry.
Re-translates two sources end-to-end through the new pipeline:
- CLAUDE.md (1 chunk, 23k chars)
- docs/architecture/ARCHITECTURE.md (14 chunks, 74k chars, one timeout retry)
Both translations now have a fresh language bar regenerated from
config/i18n.json (41 locales), an H1 heading with the native language tag,
and prose translated into Brazilian Portuguese while preserving markdown
syntax, code blocks, command names, env var identifiers, and version
numbers verbatim.
.i18n-state.json records the SHA-256 hash for each source and target. A
second invocation with no source changes correctly reports
'work units: 0 (skipped up-to-date: 2 of 2)' and `npm run i18n:check`
exits 0 — confirming the hash-based incremental + drift detection paths
both work as designed.
- Elapsed: ~10 min total at concurrency=4
- Cost: ~75k chars output through the configured backend
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
src/i18n/config.ts is now a thin adapter that reads config/i18n.json
(canonical locale list) and exports the same shape — LOCALES, LANGUAGES,
RTL_LOCALES, DEFAULT_LOCALE, Locale type, LOCALE_COOKIE — that
LanguageSelector, layout.tsx, request.ts, and the rest of the codebase
already consume. No call-site changes were required. Adds
DOCS_TARGET_LOCALES and getLanguage() helpers for new code.
The legacy scripts now print a deprecation warning on stderr at startup:
- scripts/i18n/i18n_autotranslate.py (banner + module-level warn)
- scripts/i18n/generate-multilang.mjs (banner + console.warn)
They keep working for messages and readme modes (UI strings / root README
variants), which are still outside the new pipeline's scope. Both will be
removed in v3.10.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds scripts/i18n/check-translation-drift.mjs — a deterministic CI gate that
verifies every source recorded in .i18n-state.json still hashes to the same
SHA-256 on disk and every produced translation target exists with its
recorded hash. No API calls.
Modes: --strict (default, exit 1 on any drift), --warn (exit 0 with report),
--json (machine-readable report).
Also adds three npm scripts:
- i18n:run run the translator (incremental, hash-based)
- i18n:run:dry preview what would happen (no API calls, no writes)
- i18n:check drift checker (used in CI / pre-merge)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
