// Audit environment and configuration contracts across backend settings, frontend env usage, Docker, Compose, CI, docs, and examples. Use when changing config, deployment, root paths, CORS, settings schemas, env examples, or Docker files.
| name | config-env-contract-check |
| description | Audit environment and configuration contracts across backend settings, frontend env usage, Docker, Compose, CI, docs, and examples. Use when changing config, deployment, root paths, CORS, settings schemas, env examples, or Docker files. |
| effort | medium |
Use this skill when a change touches environment variables, deployment paths, Docker, Compose, settings APIs, or docs that describe configuration.
Check these files when present:
.env.exampledocker-compose.ymlDockerfilefrontend/Dockerfilebackend/app/config.pybackend/app/api/routes/settings.pyfrontend/src/lib/api.tsfrontend/src/lib/paths.tsfrontend/vite.config.tsfrontend/vite.paths.tsfrontend/src/stores/useSettingsStore.tsscripts/check_config_contract.py ← CI contract enforcer; must be updated atomically with env var defaultsscripts/validate_vite_env.mjs ← Build-time frontend env validator; must stay in sync with inline Dockerfile validationREADME.mdINSTALLATION.mddocs/admin-guide.md.github/workflows/ci.ymlAPP_ROOT_PATH, VITE_APP_BASENAME, and VITE_API_URL aligned.When changing a default value for any env var that appears across the deployment stack, all of the following surfaces MUST be updated in the same commit:
.env.example — example/documentation valuedocker-compose.yml — Compose defaultDockerfile (root) — build-stage defaultfrontend/Dockerfile — frontend build-stage defaultscripts/check_config_contract.py — CI contract assertionMissing any one of these causes scripts/check_config_contract.py to fail in
CI with a mismatch error that is hard to diagnose without knowing all five
surfaces must agree. The script itself is part of the contract, not just an
observer of it.
Additionally: the inline validation in frontend/Dockerfile and the standalone
scripts/validate_vite_env.mjs must implement identical validation rules.
If you add or relax a check in one, update the other.
Run the repo contract check when relevant:
python scripts/check_config_contract.py
If the script fails, treat it as a config contract regression unless the script itself is stale and the intended contract has changed.
Report findings as:
Contract:
Owner:
Consumers:
Status: CONFIRMED / DISPROVED / UNVERIFIED
Evidence:
Fix:
RAGAPPv3 engineering conventions — backend (FastAPI + SQLite + LanceDB), frontend (React + TypeScript + Vite + Vitest), database/migration/RBAC patterns, and the multi-agent skill layout. Load before implementing or refactoring backend routes/services/migrations or frontend pages/components, or when you need to know "how does this repo do X".
Apply when writing tests, modifying test files, fixing test failures, debugging CI failures, adding test coverage, creating adversarial tests, or reviewing any file under tests/. Also apply when implementing features or fixes that require corresponding test changes. Enforces framework-specific rules (bun:test for TypeScript, unittest/pytest for Python), mock isolation, cross-platform compatibility, and CI pipeline awareness. Load this skill before touching any test file.
Lightweight PR-time audit for whether changes are compatible with the actual RAGAPPv3 GitHub Actions workflow, dependency lockfiles, scripts, and cross-platform local validation.
RAGAPPv3 testing policy and conventions. Load before writing or modifying any test, fixing a test/CI failure, or adding coverage. Covers backend pytest + unittest (SimpleConnectionPool dependency-override harness, FK cascades, the Python 3.11-vs-local event-loop trap) and frontend Vitest + React Testing Library + jsdom (MemoryRouter, Radix Select, react-virtual mock patterns). This repo's frontend uses Vitest, NOT bun:test.
Run a graph-guided, tool-augmented Swarm PR review using context packing, parallel exploration, triggered plugin micro-lanes, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall.
RAGAPPv3 subpath/reverse-proxy deployment system. Load before touching anything related to APP_ROOT_PATH, VITE_APP_BASENAME, VITE_API_URL, cookie paths, SPA catch-all routing, proxy configuration, or Docker build args for the frontend. Contains locked architectural decisions that must not be re-litigated.