experiential: Instructions file for Codex

Agent guide — experiential

Experiential builds immutable task evidence from agent traces, composes and fits frozen model routers, runs those routers on loopback, and executes bounded SFT from persisted datasets. All importable code lives under exp/; benchmark data arrives as a dependency (see rule 6).

Product and repository boundaries

Make open-source Experiential excellent for individual users. Keep enterprise operations, organization management, billing, and deployment orchestration in other repos. Enterprise builders can build that layer themselves, but this boundary must never compromise our gateway's performance, security, or maintainability.

Public code, documentation, commit messages, PR descriptions, and comments must describe the standalone open-source behavior. Keep private repository links, internal deployment details, customer information, and private operational or experiment evidence in private repos or local records. Limit disclosure cleanup to sensitive cases; preserve legitimate public interfaces and ordinary technical terminology. Keep shared interfaces small, performant, and reliable.

Toolchain

Managed with uv; lint/format with ruff; type-check with ty.

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run pytest -q

Repository checks

• Every new or rewritten hand-authored source, configuration, and documentation file with a covered suffix stays below 1,000 physical lines. The executable limit is 999 lines and counts comments and blank lines. Test modules named *_test.py are exempt so cohesive tests are not split solely to satisfy a line count. Generated lock files are excluded. Generated code belongs in an explicitly named generated/ directory and is never edited by hand.
• Full-repository Ruff check, Ruff format check, and ty check are required on every change. No pre-existing lint or type failures are grandfathered.
• Production imports follow the approved dependency direction: common may not import runtime, simulation, optimize, or cli; runtime may not import simulation, optimize, or cli; simulation may not import optimize or cli; optimize may not import cli. Optimize owns application orchestration and may depend inward on common, runtime, and simulation. The AST gate rejects every current forbidden edge directly and proves that the package graph is acyclic.
• The root CLI command set is exact: build, capture, config, eval, login, optimize, and run. An invocation without a subcommand opens the default gateway home screen. exp/cli/app_test.py and the release tests enforce the current command and distribution shape.