We are in an empty git repo for a codex-friendly ML research project.

0) Choose a <project_name>:
- Use the repo folder name sanitized as a Python package (lowercase, underscores). If that's not valid, default to `ml_research`.
- Use this consistently in src layout, CLI module, and docs.

1) Create a minimal "project contract" that locks key defaults and reduces ambiguity:
- Create `docs/project_contract.md` (very short, bullet list) with decisions + defaults:
  - project_name, Python version range, license
  - package manager (uv) and why
  - CLI framework choice (typer recommended) and config approach (dataclass or pydantic; pick one)
  - run records standard (what files must be written per run)
  - baseline policy (how baselines are stored/updated; no silent overwrites)
  - data policy (no data/artifacts in git; where local data lives)
- Mark unknowns as TODOs rather than guessing.

2) Create an `AGENTS.md` at repo root that is a short router (~100 lines max) defining:
- Expected repo structure (src/, tests/, configs/, scripts/, docs/).
- The ONE canonical commands interface (Makefile) and package manager commands (uv).
- The check targets: format/lint/typecheck/test/docs-check + a single `make ci`.
- Rules: keep deps minimal; prefer reproducible experiments; never commit data/artifacts; every change that affects usage must update docs minimally.
- A "safe commands" list (ok to run without asking) and a "never run" list (destructive/publish).

Also add module-specific override support: mention `AGENTS.override.md` for subtrees.

3) Add a Makefile (pick Makefile, not justfile) exposing:
- `make setup`, `make format`, `make lint`, `make typecheck`, `make test`, `make docs-check`, `make ci`
- Add `make train-smoke` and `make eval-smoke` placeholders for later.

4) Add repo “boring files” that prevent ambiguity:
- `README.md` with: quickstart, `make setup`, `make ci`, how to run train/eval (placeholder now), where outputs go, where docs live.
- `LICENSE` (MIT by default unless the project contract says otherwise).
- `CONTRIBUTING.md` (how to run checks, expected PR hygiene, docs updates).
- `.github/pull_request_template.md` (what changed, how tested, docs touched).
- `CITATION.cff` (minimal, with placeholder authors if unknown).

5) Validate in an empty repo:
- Ensure docs/ exists with at least `docs/index.md` (can be tiny) that links to `project_contract.md`.
- Run whatever commands make sense to confirm Makefile targets don’t error even if some are no-ops.
- Print the resulting top-level tree.

Scaffold this repository into a modern, codex-friendly ML research Python project.

Requirements:
- Use a `src/` layout (importable package under `src/<project_name>/`).
- Create `pyproject.toml` with:
  - ruff (lint + format)
  - pytest
  - mypy (or pyright; pick one and wire it into `make typecheck`)
  - a clean dependency grouping strategy (dev/test/optional extras)
- Add `.gitignore` suitable for ML research (data/, runs/, checkpoints/, wandb/, .venv/, etc.).
- Add `.pre-commit-config.yaml` that runs the same checks as CI.
- Add GitHub Actions CI to run on push/PR: format/lint/typecheck/tests.
- Keep the default runtime deps minimal; heavy ML deps (torch, etc.) may be optional extras unless you need them for the example code.

Deliver a minimal runnable package with:
- `src/<project_name>/__init__.py`
- `src/<project_name>/cli.py` that has `train` and `eval` subcommands (can be stubbed but runnable)
- `tests/test_smoke.py` that passes.
  
Update the Makefile targets so they actually work:
- `setup` creates/uses a local venv (uv) and installs dev deps
- `format` runs ruff format
- `lint` runs ruff check
- `typecheck` runs mypy
- `test` runs pytest
- `docs-check` for now just validates docs/index links exist + required docs files exist (keep it minimal; expand later)
- `ci` runs all of the above

Finally: run `make ci` and fix anything until it passes.

Now add the minimal ML research “application framework” on top of the scaffold.

Core requirements (keep it small but real):
1) Config + determinism:
- Use a config object (dataclass or pydantic—must match the project contract).
- Include a default config file in `configs/` (e.g., `configs/default.yaml`).
- Deterministic seeding (python/random/numpy; if torch is present, seed torch too).

2) Standardized run records (REQUIRED):
- Every `train` invocation must create a unique run directory under `runs/<run_id>/` (runs/ is gitignored).
- Run directory MUST include:
  - `config_resolved.yaml` (full resolved config)
  - `command.txt` (exact CLI invocation)
  - `git.txt` (commit SHA + "dirty" status; if git unavailable, write "unknown")
  - `env.json` (python version, platform, timestamp, optional cuda availability)
  - `deps.txt` (best-effort dependency snapshot; try `uv pip freeze`, fallback to `python -m pip freeze`)
  - `metrics.json` (train + eval metrics, even if tiny)
  - a saved artifact (e.g., `artifact.pkl` or `model.pt` depending on deps)

3) Logging:
- Structured logging to stdout and to `runs/<run_id>/train.log`.

4) Minimal Dataset/Model:
- Provide a placeholder Dataset + Model abstraction with a simple baseline (e.g., linear regression or tiny MLP).
- The entire `train` must run end-to-end in < 30 seconds on CPU.

5) Eval:
- `eval` must accept `--run-id`; if omitted, evaluate the latest run.
- It loads the saved artifact and prints a metric, also writing eval results into the run dir (update `metrics.json`).

6) Baseline protection (REQUIRED; no silent overwrites):
- Store tracked baselines under `baselines/` (committed to git), e.g. `baselines/default.json`.
- `eval` should compare current metrics to the baseline (if it exists) and print a short comparison.
- Add a CLI subcommand group `baseline` with:
  - `baseline show`
  - `baseline compare --run-id <id>` (or default latest)
  - `baseline update --run-id <id> --reason "<text>"`:
    - updates `baselines/default.json` ONLY via this command
    - appends an entry to `docs/decisions/baseline_updates.md` with date, old vs new, run-id, command, git SHA, and the provided reason.
- Make it hard for agents to overwrite baselines accidentally: do NOT write to baselines anywhere else.

7) Tests (fast):
- Validate `train` creates a run dir with the required files.
- Validate `eval` runs successfully on the produced run.
- Validate baseline update workflow:
  - baseline update requires a reason
  - baseline file changes + baseline_updates.md appended

8) Makefile:
- Implement `make train-smoke` and `make eval-smoke` using the CLI and default config.
- Keep `make ci` fast; if train-smoke is too slow for CI, keep it as a separate target but ensure tests cover the same behavior.

Finally:
- Run `make ci` again and ensure everything passes.

Create a minimal docs/ knowledge base as the system of record, but avoid over-scaffolding.

Constraints:
- Progressive disclosure: `docs/index.md` is the router (short TOC).
- Only create essential sections + templates. Do NOT create lots of placeholder content.
- Add `docs/doc_style.md` defining required front-matter fields for docs:
  - Status (Draft/Verified), Last reviewed date, Owner(s), Related code paths
- Keep docs factual; avoid project-specific guesses beyond what exists in code.

Create only these (minimal but real):
- `docs/index.md` (TOC + links)
- `docs/project_contract.md` (already exists; ensure it links back to index)
- `docs/architecture.md` (1–2 pages max; point to key code paths)
- `docs/runbooks/index.md` + `docs/runbooks/quickstart.md` (how to setup, run checks, train/eval)
- `docs/runbooks/codex.md` (how instructions are organized, how to run summaries, doc size cap note, how overrides work)
- `docs/decisions/index.md`
	- `docs/decisions/adr_template.md` (template only)
- `docs/decisions/baseline_updates.md` (append-only log; baseline update command writes here)
- `docs/exec-plans/index.md` + `docs/exec-plans/template.md` + directories `docs/exec-plans/active/` and `docs/exec-plans/completed/` (include a tiny README in each dir so it’s tracked)
- `docs/references/index.md`

Update `AGENTS.md` minimally:
- Add ONE line pointing to `docs/index.md` and ONE line pointing to the baseline policy location.

Add a real `make docs-check`:
- Verify `docs/index.md` links point to existing files.
- Verify required doc files exist.
- Verify `docs/decisions/baseline_updates.md` exists.
- List the docs tree.

Finally:
- Run `make docs-check` and `make ci`.

Doc gardening sweep (repo-wide).

Goal: find and fix documentation drift without inventing new docs.

Steps:
1) Scan docs/ for staleness signals:
   - docs mention files/modules that don’t exist
   - commands don’t match Makefile/CLI
   - baseline policy conflicts with current baseline workflow
2) Cross-check against current tree and the last 50 commits if available.
3) Produce a prioritized list of doc issues (high/med/low) with evidence.
4) Apply fixes for high/medium issues directly in docs/.
5) For judgment calls: create an ADR stub under docs/decisions/ or add a TODO in the relevant doc (don’t guess).

Finally:
- run `make docs-check` and `make ci` if available
- write a short report under `docs/exec-plans/completed/doc_gardening_report.md` summarizing:
  - what changed
  - what remains open
  - why this improves legibility for agents

Create a minimal, high-leverage set of Codex Agent Skills for this ML research repository.

Context / constraints:
- Skills must be saved under `.agents/skills/` (repo-scoped).
- Each skill is a folder containing a required `SKILL.md` with YAML frontmatter `name` and `description`.
- Keep each `SKILL.md` concise and action-oriented. Do NOT duplicate large policy text inside skills.
- This repository uses a docs-as-system-of-record approach:
  - AGENTS.md is a short map (~100 lines).
  - docs/ contains the actual source of truth (runbooks, research specs, ADRs, exec plans).
- Therefore: skills should primarily (1) point to the relevant docs pages, (2) enforce workflows, and (3) produce consistent artifacts.

Deliverables:
1) Create these 5 skills (exact folder names and skill names):
   - `.agents/skills/ml-exec-plan/SKILL.md`
   - `.agents/skills/ml-new-experiment/SKILL.md`
   - `.agents/skills/ml-results-snapshot/SKILL.md`
   - `.agents/skills/ml-docs-delta/SKILL.md`
   - `.agents/skills/ml-docs-gardener/SKILL.md`

2) For each SKILL.md:
   - Include YAML frontmatter:
     ---
     name: <skill-name>
     description: <a crisp description that explains exactly when the skill SHOULD and SHOULD NOT trigger>
     ---
   - Then include these sections (keep each section short but concrete):
     - “When to use this”
     - “When NOT to use this”
     - “Inputs you must gather”
     - “Files to consult first” (link to relevant `docs/...` pages; do not restate their contents)
     - “Steps” (numbered, executable workflow; prefer deterministic steps like running make targets)
     - “Definition of done” (bullet list of verifiable conditions)
     - “Failure modes & escalation” (when to stop guessing and record an ADR / add tech debt item)

3) Skill-specific behavior requirements:

   A) ml-exec-plan
   - Purpose: create an execution plan artifact for non-trivial work.
   - Output: a new file in `docs/exec-plans/active/` with a consistent naming scheme (date + short slug).
   - Must include: goal, scope, non-goals, risks, validation plan, and a running decision log section.
   - Must link to any relevant existing ADRs or create an ADR stub if needed.

   B) ml-new-experiment
   - Purpose: add a new experiment in a repeatable way.
   - Must:
     - create a new config file under `configs/` (or the repo’s config area)
     - add a new experiment module / entry point under `src/`
     - add/extend a minimal test that ensures the experiment code imports and a dry-run works
     - add a docs entry under the experiment registry doc in `docs/` (create the registry doc if missing)
   - Must run the lightest possible end-to-end check (e.g., a “dry run” or 1-epoch CPU run) and record where outputs go.
   - Must never add large datasets to git; should reference docs runbook for data handling.

   C) ml-results-snapshot
   - Purpose: produce a reproducible “result snapshot” (metrics + artifacts) and update docs.
   - Must:
     - run eval and capture metrics to a stable location (gitignored artifact dir, but docs updated)
     - update a results table or markdown section in docs with date, command, config reference, and metric values
     - avoid silently overwriting prior results; if a baseline changes, record why + link to code change
   - Must include a “compare to baseline” step where possible.

   D) ml-docs-delta
   - Purpose: keep docs accurate after code changes.
   - Must:
     - inspect current git diff (or latest commits)
     - map each change to the doc page(s) that should reflect it
     - update docs minimally and precisely
     - explain why docs were/weren’t changed
   - Must run `make docs-check` if present, otherwise do basic link/file existence checks.

   E) ml-docs-gardener
   - Purpose: periodic repo-wide documentation drift cleanup.
   - Must:
     - scan docs/ for stale claims (commands that no longer work, paths that no longer exist, contradicted architecture)
     - cross-check against current tree and recent commit history
     - produce a prioritized issue list (high/med/low) with evidence
     - apply fixes for high/medium items; for judgment calls create ADR stubs or add tech-debt entries
     - write a gardening report under `docs/exec-plans/completed/` summarizing what changed and what remains.

4) Integrate into the docs knowledge base:
- Add a short `docs/references/skills.md` that lists these skills, what they do, and how to invoke them (e.g., `$ml-docs-delta`).
- Update `docs/index.md` to link to `docs/references/skills.md`.
- If AGENTS.md exists, add ONE line pointing to `docs/references/skills.md` (do not bloat AGENTS.md).

5) Verification:
- Print the resulting `.agents/skills/` tree.
- Confirm each SKILL.md has valid YAML frontmatter with `name` and `description`.
- (If available in this environment) run `/skills` or otherwise confirm the skills are discoverable.

Make the changes directly in the repo.

Skills Management Sweep (short, repo-only).

Goal:
- Propose new high-leverage skills from repeated work patterns.
- Detect unused/redundant skills and deprecate/merge them safely.

Constraint:
- Use ONLY repo evidence (no chat hallucination). If “recent chat sessions” aren’t accessible, approximate via:
  - docs/exec-plans/{active,completed}/
  - docs/decisions/*
  - git log/diffs
  - ripgrep for `$ml-` (explicit skill invocations) and recurring file-change patterns

Steps:
1) Inventory skills
- List `.agents/skills/*/SKILL.md`.
- Create/update `docs/references/skills_inventory.md` (1 table: skill, purpose, main outputs, consult-first docs).

2) Usage check (evidence-based)
- Use `git log -n 200 --name-only` + ripgrep to find signs each skill was used.
- Create/update `docs/references/skills_usage.md` with 3 buckets: Used / Weak evidence / No evidence (include 1–2 concrete evidence lines each).

3) New skill opportunities
- From exec plans + recurring diffs, identify repeated tasks with clear inputs/outputs.
- For each candidate: 2–3 bullets: “When to use”, “Produces”, “Verifies with (make targets)”.
- Implement ONLY candidates backed by evidence (else add a “skill idea” note in docs and stop).

4) Prune/merge safely
- For unused/overlapping skills: don’t delete; mark DEPRECATED at top of SKILL.md with reason + replacement + last reviewed date.
- If a skill is too broad: narrow its `description` decision boundary so it won’t mis-trigger.

5) Wire a fast check
- Add `make skills-check`:
  - verify each SKILL.md has YAML frontmatter with `name` and `description`
  - verify required sections exist (When to use/NOT, Inputs, Steps, DoD, Failure modes)
- Include `skills-check` in `make ci`.

6) Write a short audit report
- Create `docs/exec-plans/completed/skills_audit_<YYYY-MM-DD>.md` with:
  - evidence examined
  - skills added/updated/deprecated (why)
  - verification run results: `make skills-check`, `make docs-check`, `make ci`

Finally:
- Print `.agents/skills/` tree and run: `make skills-check && make docs-check && make ci`.

name: run-experiment
description: |
  Use when: you need to add or run a training/eval experiment in this repo using configs/.
  Don’t use when: you’re just editing docs or making a trivial code change.
  Inputs: config path, expected compute budget, run name.
  Outputs: run directory with manifest + metrics; short run summary; links/paths to artifacts.
---

## Safety / cost gates
- If expected cost > $X or GPU hours > Y, ask for confirmation before launching.
- Never modify production datasets or shared buckets without explicit confirmation.

## Steps
1) Validate config
   - Run: `python -m project.validate_config --config <...>`
   - Expected: exits 0; prints resolved config.

2) Run smoke (cheap)
   - Run: `make smoke` OR `python -m project.train --config <...> --max_steps 5`
   - Expected: training loop works; metrics file created.

3) Launch full run (only after confirmation if expensive)
   - Command: `python -m project.train --config <...> --run_name <...>`
   - Ensure run manifest includes git SHA and diff hash.

4) Summarize results
   - Run: `python -m project.summarize_run runs/<id>`
   - Output: markdown summary + key plots saved under runs/<id>/artifacts/

## Definition of done
- Run completed successfully or failed with a clear error + next actions.
- Summary produced with metrics + artifact paths.

## Common failure modes
- CUDA OOM → suggest batch size / grad checkpointing; log config diff
- Data not found → check docs/datasets.md and env vars

Add a Makefile to this repo for the reproducibility and testing following the style of this Makefile: SRC = src/
  SCRIPTS = scripts/
  TESTS = tests/
  DOCS = docs/
  ALL_CODE = ${SRC} ${SCRIPTS} ${TESTS}

  format:
  	uvx ruff check ${ALL_CODE} --select I --fix
  	uvx ruff format ${ALL_CODE}
  lint:
  	uvx ruff check ${ALL_CODE}
  docs-lint:
  	uvx pymarkdownlnt scan *.md
  	uvx pymarkdownlnt scan --recurse ${ALL_CODE} ${DOCS}
  test:
  	uv run pytest ${TESTS} -m "not slow"
  test-full:
  	uv run pytest ${TESTS}
  static:
  	uv run mypy ${SRC} ${SCRIPTS}
  prepare: format lint docs-lint static test
  prepare-full: format lint docs-lint static test-full

  clean:
  	rm -rf .mypy_cache .pytest_cache .ruff_cache

DO the same for an AGENTS.md for codex. Make it professional, following the style of this one: # AGENTS.md

  Guidelines for AI agents working on this codebase.

  ## Development Workflow

  - Run `make prepare` after any code edits; it handles formatting, linting, static type-checking, and tests.
  - Restate the planned steps and confirm expectations for complex requests so reviewers have a clear receipt of decisions and next actions.
  - Use `uv run python ...` for scripts.
  - Manage dependencies with `uv add` / `uv remove`; don't edit `pyproject.toml` directly when adding dependencies.
  - Important design decisions should be tracked in `docs/decision-log.md`

  ## Approvals & Escalations

  - Request escalated permissions when a command needs filesystem access outside the workspace, writes to protected locations, or requires network access.
  - If sandboxed commands fail due to permissions or connectivity, rerun them with approval instead of hacking around the restriction.
  - Include a one-line justification when requesting approval so reviewers understand the need.
  - Treat destructive operations (e.g., `rm`, `git reset --hard`) as opt-in only when the user explicitly asks for them.

  ## Code Quality & Style

  - Favor maintainable, easy-to-read code even if that drops niche backward compatibility; call out intentional behavior changes.
  - Refactor aggressively to remove dead code and simplify APIs; once code is no longer used, delete it.
  - Keep attribute access shallow; expose necessary data locally.

  ## Testing

  - Mirror every bug fix or new feature with a failing test first and keep golden files or fixtures as small as possible.
  - Keep the `tests/` directory structure aligned with `src/pensieve/`; e.g., `src/pensieve/model/config.py` pairs with `tests/pensieve/model/test_config.py`.
  - Keep tests deterministic by seeding randomness (e.g., `torch.manual_seed`, `numpy.random.seed`) when necessary.
  - Avoid mocking and patching unless absolutely necessary; prefer dependency injection instead.
  - Prefer unit-level coverage where possible; use integration test suites for end-to-end coverage only when necessary.

  ## Error Handling

  - Fail fast with explicit, informative errors instead of silent fallbacks.
  - When user input is invalid, raise clear exceptions.

  ## Workflow Reminders

  - Deliver exactly what was requested and ask clarifying questions when uncertain.
  - Surface missing context proactively - pause to request any blocking information before acting.
  - Avoid creating separate documentation files unless the user explicitly asks for them; prefer docstrings and comments.

Create a minimal docs/ knowledge base as the system of record, but avoid over-scaffolding.

Constraints:
- Progressive disclosure: `docs/index.md` is the router (short TOC).
- Only create essential sections + templates. Do NOT create lots of placeholder content.
- Add `docs/doc_style.md` defining required front-matter fields for docs:
  - Status (Draft/Verified), Last reviewed date, Owner(s), Related code paths
- Keep docs factual; avoid project-specific guesses beyond what exists in code.

Create only these (minimal but real):
- `docs/index.md` (TOC + links)
- `docs/architecture.md` (1–2 pages max; point to key code paths)
- `docs/runbooks/index.md` + `docs/runbooks/quickstart.md`
- `docs/runbooks/codex.md` (how instructions are organized, how to run summaries, doc size cap note, how overrides work)
- `docs/decisions/index.md`
	- `docs/decisions/adr_template.md` (template only)
- `docs/decisions/baseline_updates.md` (append-only log; baseline update command writes here)
- `docs/references/index.md`

Update `AGENTS.md` minimally:
- Add ONE line pointing to `docs/index.md` and ONE line pointing to the baseline policy location.

Add a real `make docs-check`:
- Verify `docs/index.md` links point to existing files.
- Verify required doc files exist.
- Verify `docs/decisions/baseline_updates.md` exists.
- List the docs tree.

You are an expert ML researcher who knows how to find the important bits of information within a research paper. I am studying the literature in ----------- and I want to understand the fundamental problems that need to be solved.

First, distill the core arguments of this paper, understand the real motivations, and how this paper is positioned compared to previous work

Next, provide a detailed analysis of the methodology and what their unique approach is. If possible, make a table with their methods used, stating what is a new, less common, or common approach is compared with previous art.

Do your analysis in depth, focusing on what really matters.

Ok, I. understand. Following your analysis, create a detailed explanation in plain-text of ------------- and answers the following questions: question_1, question_2, question_3

I am working on a research project structured around weekly iteration cycles, with at least one meaningful, decision-grade experimental iteration per week. Each iteration is defined by a hypothesis or goal and a corresponding set of experiments.

For each report, I will provide:

- Documentation on the current hypothesis
- Annotated experimental results
- Plots for the results.
- Additional project context
- Previous scientific reports (where available)
  
Your task is to write a scientific report covering the current hypothesis and experimental results. Follow these design principles when writing the report:

- First, it must highlight the hypothesis for the experiments.
- Second, it must include a TL;DR or “key takeaway” paragraph at the top and a  decision on the next step: continue, pivot, or stop.
- Third, it must list each set of experiments with: (1) goal/question, (2) key result/finding, (3) decision/conclusion. Make it clear and concise, and refer to the Methodology section below for all the details. Include the plots provided.
- Finally, it must include all the additional information about the experimental setup and all the supporting details.

You are a codebase-explainer agent. Your job is to help a new Research Scientist understand this repository well enough to run experiments, modify models, and debug failures.

HARD RULES
- No hallucinations: every non-trivial claim must be grounded with references:
  - include file path(s) + symbol name(s) + line ranges (or exact snippets) that justify the claim.
  - if you’re uncertain, say “Unknown” and propose the exact file/command to verify.

WHAT TO PRODUCE (deliverables)
1) “Codebase in 15 minutes” (skim-friendly)
   - What this repo does, in 8–12 bullets.
   - The 3–5 most important entry points (CLI, scripts, notebooks, services).
   - The standard workflow to run an experiment end-to-end.
   - Each bullet must cite paths + line ranges.

2) Architecture map (detailed but understandable)
   - A component diagram (Mermaid) showing major packages/modules and how data flows.
   - For each component: purpose, key classes/functions, inputs/outputs, where configs live.
   - Call out boundaries: training loop, models, datasets, evaluation, logging, orchestration.
   - Cite paths + line ranges for each component mapping.

3) “How do I run things?”
   - Exact commands for: install/setup, unit tests, lint/format, a minimal training run, evaluation, and reproduction of a known run (if supported).
   - Identify the package manager / environment system (e.g., uv/poetry/pip/conda), and where dependencies are declared.
   - Identify where seeds, determinism flags, and hardware settings (GPU/CPU) are configured.
   - Cite paths + line ranges for commands/config.

4) Key workflows (explain like I’m new to the repo)
   - Training: from config → dataloader → model → loss → optimizer → checkpoint → metrics.
   - Evaluation: what metrics, where computed, how aggregated, where results saved.
   - Experiment tracking: logging framework, run directory structure, artifacts produced.
   - For each workflow, include a step-by-step trace with pointers to the exact functions called.

5) Glossary + “Where to change what”
   - Glossary of repo-specific terms (dataset names, abbreviations, “run”, “trial”, etc).
   - A table: “If you want to X, edit Y” (e.g., add dataset, add model, change scheduler, add metric).
   - Cite paths + symbols.

6) Risks / footguns / debugging guide
   - Top 10 failure modes you anticipate in this repo (mismatched shapes, config gotchas, device issues, caching, mixed precision, etc.).
   - For each: symptoms, likely cause, where to look first, and a suggested debug command/print.
   - Cite the relevant code areas.

PROCESS (how you should work)
A) First scan:
   - Print a compact tree of the repo (top-level + src/ + key folders).
   - Identify languages/frameworks (PyTorch/JAX/etc), configs (yaml/json/hydra/gin), and orchestration.
B) Then deep dive:
   - Locate: main entry points, config system, dataset pipeline, model definitions, training loop, eval loop, logging/tracking, checkpointing.
   - Trace one “golden path” execution flow from CLI/script to training step; include the call chain.
C) Output formatting:
   - Use headings and short paragraphs; keep it readable.
   - Every section must include citations (paths + line ranges).

START NOW
1) Show the repo tree and list the likely entry points.
2) Produce the six deliverables above in one response, in this order.
3) End with: “Open questions” + “Suggested reading order (90 minutes)” + “Next 5 questions you recommend I ask”.

The codebase is meant for research agent to run experiments autonomously. However, I also want to use coding agents as assistant for improving the codebase, NOT as the research agent. To do so, I want to have a clear AGENTS.md file that is used by the coding assistant agent, and NOT by the research agent. 
  
Write the AGENTS.md making use that the research agent does not use it or adds it into context. Write the AGENTS.md following these instructions:
  
Guidelines for AI agents working on this codebase.

## Development Workflow
- Run `make prepare` after any code edits; it handles formatting, linting, static type-checking, and tests.
- Restate the planned steps and confirm expectations for complex requests so reviewers have a clear receipt of decisions and next actions.
- Use `uv run python ...` for scripts.
- Manage dependencies with `uv add` / `uv remove`; don't edit `pyproject.toml` directly when adding dependencies.

## Approvals & Escalations
- Request escalated permissions when a command needs filesystem access outside the workspace, writes to protected locations, or requires network access.
- If sandboxed commands fail due to permissions or connectivity, rerun them with approval instead of hacking around the restriction.
- Include a one-line justification when requesting approval so reviewers understand the need.
- Treat destructive operations (e.g., `rm`, `git reset --hard`) as opt-in only when the user explicitly asks for them.

## Code Quality & Style

- Favor maintainable, easy-to-read code even if that drops niche backward compatibility; call out intentional behavior changes.
- Refactor aggressively to remove dead code and simplify APIs; once code is no longer used, delete it.
- Keep attribute access shallow; expose necessary data locally.

## Testing

- Mirror every bug fix or new feature with a failing test first and keep golden files or fixtures as small as possible.
- Keep the `tests/` directory structure aligned with the rest of the codebase.
- Keep tests deterministic by seeding randomness (e.g., `torch.manual_seed`, `numpy.random.seed`) when necessary.
- Avoid mocking and patching unless absolutely necessary; prefer dependency injection instead.
- Prefer unit-level coverage where possible; use integration test suites for end-to-end coverage only when necessary.

## Error Handling

- Fail fast with explicit, informative errors instead of silent fallbacks.
- When user input is invalid, raise clear exceptions.

## Workflow Reminders

- Deliver exactly what was requested and ask clarifying questions when uncertain.
- Surface missing context proactively - pause to request any blocking information before acting.
- Avoid creating separate documentation files unless the user explicitly asks for them; prefer docstrings and comments.

These are my personal notes for collecting good practices on how to use LLM agents in different settings. These notes are a living document that I keep updating while discovering new good practices and building experience with LLM agents. These notes are not supposed to be perfectly lean.

The notes follow a ATX-style headings. I keep personal notes between a Heading (one #) or a Heading 2 (two #) and the next "--". Follow these rules:
1. Do NOT consider the text between a Heading or Heading 2 and the next "--".
2. Do not consider the code parts of the text.
   
Do these steps in order:
1. Provide a detailed analysis of the current status of the notes.
2. Highlight where I could increase clarity.
3. Highlight where I could add relevant information.