Synaptic-Tuner: Instructions file for Codex

Project Agent Notes

This repository has a few cloud-training constraints that are easy to relearn the hard way.

Fine-Tuning Workflow Discipline

• Runtime profiles MUST be configuration-driven. Recipes select named profiles; profile data declares exact model/revision/method compatibility, immutable image/inventory and associated build configuration. Planning and execution must resolve the same bound selection. Never add model-specific profile constants, switches or fallback mappings to a launcher. A candidate profile permits qualification, not a claim of successful model/hardware qualification; retain independent smoke evidence before promotion.

• For any task in this repo, begin by loading the most relevant canonical skill from .skills/. For fine-tuning, cloud training, evaluation, experiment-loop, checkpoint-eval, model-selection, or dataset-publishing work, that starting point is usually the fine-tuning skill.

• .skills/ is the canonical skill source for this repo. .agents/skills and .claude/skills are synced copies and must match it exactly.

• After changing canonical skills, run python3 .skills/scripts/sync_skill_trees.py and verify with python3 .skills/scripts/sync_skill_trees.py --check.

• Before building a new script, helper, or one-off workflow to run something, first check whether the needed command, script, CLI surface, or skill guidance already exists in the repo.

• Do not create throwaway scripts just to get a task done if an existing script, CLI, or skill can be used or extended.

• If the capability does not exist, the next step is not an ad hoc workaround. Update the relevant skill and add the proper checked-in script/CLI workflow so the new capability is reusable.

• Prefer repo CLIs and checked-in scripts over manual bucket/API probing whenever those surfaces exist.

• Diagnose failures from the exact attempt's retained records, logs, pinned SDK source, and provider documentation. Use relevant issue/forum reports to form hypotheses, then run a targeted experiment before calling a hypothesis the cause. A closed failure phase locates a boundary; it does not establish the cause.

• Offline SFT worker diagnostics may emit only closed phase/category/milestone labels, never exception text, paths, argv, environment values or traceback frames. Preserve the consumed attempt; a historical generic rejection cannot be assigned a later diagnostic stage. Refresh all affected SFT/GRPO closures and Modal training/inference locks before fresh qualification.

• Keep the training workflow proportional to the supported use case. Remove redundant operations when documented behavior and experiments show they add no useful guarantee; retain source/model pins, credential isolation, artifact verification, and protection against replaying an uncertain submission. Test doubles must model the provider's documented behavior, not merely repeat our implementation.

• For prompt/completion training, explicitly review the generation scaffold at the target boundary and keep model-specific chat-template arguments in recipe configuration, consistent with serving. Preserve legacy canonical documents when optional arguments are absent. An explicit null output budget means no request-level token ceiling, not unlimited context, time, or transport size. A completed-text smoke must check natural completion and must not be reported as a writing-quality evaluation.