Add program.md to system context and clean up docs/

.agents/agents/search.md

@@ -4,9 +4,6 @@ description: |
   Use for external research through the explicit search_general_web task form
   for current public sources, or search_research_publications for scholarly
   literature through Exa and primary papers.
-
-  <example>Find the current API behavior in official documentation.</example>
-  <example>Survey publications on conservative neural operators for CFD.</example>
 model: inherit
 reasoning_effort: inherit
 permission_mode: never_confirm

.agents/skills/exa-search/SKILL.md

@@ -18,7 +18,7 @@ python "$HOME/.agents/skills/exa-search/scripts/search_exa.py" \
 ```bash
 python "$HOME/.agents/skills/exa-search/scripts/search_exa.py" \
   research-publications \
-  "mesh-based neural operators for aerodynamic surrogate modeling"
+  "uncertainty calibration for neural networks"
 ```
 
 The script returns Markdown rather than raw JSON. Each result contains a direct

.agents/skills/senpai-status-check/SKILL.md

@@ -9,9 +9,7 @@ description: Produce a fresh, read-only status report for a Senpai research trac
 
 # Senpai status check
 
-Report what the configured research programme and fleet are doing now. Keep
-scientific progress separate from infrastructure liveness, and distinguish
-observed evidence from inference.
+Report progress against the configured `program.md` and fleet activity now. Keep scientific progress separate from infrastructure liveness, and distinguish observed evidence from inference.
 
 ## Establish scope
 
@@ -29,9 +27,7 @@ Resolve these values from the environment before collecting evidence:
 If a required value is absent, record an evidence gap. Never substitute a
 remembered repository, branch, cluster, project, dataset, or metric.
 
-Read `$TARGET_WORKDIR/program.md` for the programme's goals, metric contracts,
-benchmarks, training constraints, and permitted reporting paths. Derive every
-metric and benchmark in the report from that file or live evidence.
+Read the `program.md` identified in the system prompt for its goals, metric contracts, benchmarks, training constraints, and permitted reporting paths. Derive every metric and benchmark in the report from that file or live evidence.
 
 ## Collect bounded evidence
 

AGENTS.md

@@ -4,46 +4,65 @@ SPDX-License-Identifier: Apache-2.0
 SPDX-PackageName: senpai
 -->
 
-# senpai - Development Context
+# senpai - Project Context
 
-Development of a problem-agnostic autonomous ML research loop for target ML
-problem repositories. The current research programs are often CFD surrogate
-experiments, but the runner should stay target-repo agnostic.
+## Senpai users
 
-## User Clarifications
+### Creating a target program.md
+
+When helping a user onboard a target repository, inspect an explicitly configured `program_path` first. When it is blank, look for `program.md` at the root and exactly one directory below it. If there is no usable file, coach the user through creating one. Inspect the repository before interviewing them, establish facts yourself, ask the user to decide the remaining intent and tradeoffs, and wait for shared understanding before drafting the file. Multiple auto-discovered files are ambiguous; do not choose one silently.
+
+`program.md` is appended to every Senpai model's system prompt, so keep it concise, plain-language, and high-signal. It should clearly define:
+
+- the project goal and the exact primary metrics, including how each metric is calculated, which direction is better, and which split or benchmark decides success;
+- the data paths, shapes, sizes, train/validation/test splits, exclusions, leakage risks, and important footguns;
+- operational guardrails such as commands, budgets, allowed edits, protected artifacts, and result-reporting expectations; and
+- optional research avenues, papers, models, and libraries that provide useful starting points without forcing a narrow solution path.
+
+Favor high-level goals and guardrails that let research agents discover the details. Avoid micromanaging methods or over-prompting one idea unless that narrow focus is the user's explicit goal. The [`bootstrap-target`](plugins/senpai/skills/bootstrap-target/SKILL.md) guide and its template can turn the confirmed decisions into the target contract.
+
+Reference examples:
+
+- [TandemFoilSet-Balanced](https://github.com/morganmcg1/TandemFoilSet-Balanced/blob/main/program.md)
+- [DrivAerML](https://github.com/morganmcg1/DrivAerML/blob/main/program.md)
+- [MLXFast challenge](https://github.com/morganmcg1/mlxfast-challenge_senpai/blob/main/senpai/program.md)
+- [autoresearch](https://github.com/karpathy/autoresearch/blob/master/program.md)
+
+## Senpai developers
+
+Development of a problem-agnostic autonomous ML research loop for target ML problem repositories. The runner and its guidance must stay target-repo agnostic.
+
+### Clarifying development work
 
-### Interviewing the developer about how to do a task:
 When asked for a large piece of work that seems vague, consequential, or full
 of hidden tradeoffs, ask the user detailed clarifying questions about the real
 implementation choices: technical design, workflow, UX, risks, validation,
 operations, and tradeoffs. Prefer non-obvious questions that expose constraints
 or intent. When the answers change durable project behavior, write the learnings
 to README.md or SPEC.md as appropriate.
 
-
-## Coding guidelines and philosophy
+### Coding guidelines and philosophy
 
 - You should generate code that is simple and readable. Avoid unnecessary abstractions and complexity. This is a research codebase, so maintainability and clarity matter.
 - Avoid overly defensive coding. No need for lots of `try`/`except` patterns, fallbacks, or backups. Prefer code that fails clearly when something is wrong so it can be fixed.
 - Do not add demo-only flags or placeholder CLI options that gate real functionality (e.g., `--run` just to toggle execution); scripts should run their main logic directly.
 - Adhere to the repository's Python 3.13 runtime.
 
-## Key docs
+### Key docs
 
 - `README.md` - operator-facing overview, launch examples, and problem-package layout.
 - `SPEC.md` - target architecture and rewrite contract for the senpai orchestration loop.
-- `senpai.yaml` - launch defaults, including the target repo, target branch, advisor branch, and `problem_dir`.
-- `$PROBLEM_DIR/program.md` - authoritative target research context, goals, metrics, training constraints, and file boundaries. With the default config this is `target/program.md` after the target repo is cloned.
-- `$PROBLEM_DIR/instructions/prompt-advisor.md` - target-specific advisor prompt.
-- `$PROBLEM_DIR/instructions/prompt-student.md` - target-specific student prompt.
+- `senpai.yaml` - launch defaults for the Senpai runner, target branch, advisor branch, and `problem_dir`; supply the required target repository by CLI or local config.
+- `$PROBLEM_DIR/program.md` - conventional authoritative target research context, goals, metrics, training constraints, and file boundaries. A blank `program_path` requires exactly one `program.md` across the repository root and directories one level below; an explicit value selects a target-repository-relative `program.md`.
 - `system_instructions/SENPAI-HARNESS.md` - shared OpenHands harness contract.
 - `system_instructions/ADVISOR.md` - advisor role workflow.
 - `system_instructions/STUDENT.md` - student role workflow.
+- `system_instructions/SENPAI-LAUNCH-CONTEXT.md` - authoritative per-launch runtime and isolation rules.
 
-## Architecture
+### Architecture
 
 - **Runner repo** - this repo. Owns orchestration, Kubernetes launch, role instructions, GitHub helpers, W&B integration, and operational docs.
-- **Target repo** - cloned into `$PROBLEM_DIR` from `target_repo_url`. Owns the data code, training code, evaluation code, `program.md`, target prompts, and experiment branches. Agent commits and PRs land in the target repo, not in the runner repo.
+- **Target repo** - cloned into `$PROBLEM_DIR` from `target_repo_url`. Owns the data code, training code, evaluation code, `program.md`, project context, and experiment branches. Agent commits and PRs land in the target repo, not in the runner repo.
 - **Advisor pod** - lightweight, no GPU, keeps one durable OpenHands
   conversation and uses typed control-plane tools for GitHub and generic
   child-agent dispatch.
@@ -55,22 +74,21 @@ to README.md or SPEC.md as appropriate.
 - **GitHub Issues** - human-to-agent communication channel. Agents poll for and respond to these alongside their normal PR workflow.
 - **W&B** - canonical experiment metrics store for training runs, comparisons, and merge decisions.
 
-## k8s layout
+### k8s layout
 
 - `k8s/advisor-deployment.yaml` / `k8s/student-deployment.yaml` — pod specs
 - `k8s/entrypoint-advisor.sh` / `k8s/entrypoint-student.sh` — startup scripts
 - `k8s/launch.py` — helper to template and apply deployments
 
-## system_instructions/
+### system_instructions/
 
-The OpenHands base prompt is extended with a stable merged suffix from the
-shared harness file and one rendered role file:
+The OpenHands base prompt is extended with one stable system suffix, assembled in this order:
 
 - `system_instructions/SENPAI-HARNESS.md`
-- `system_instructions/ADVISOR.md` or
-  `system_instructions/STUDENT.md`
+- `system_instructions/ADVISOR.md` or `system_instructions/STUDENT.md`
+- the selected target `program.md`, with its repository-relative path in the header
+- the rendered `system_instructions/SENPAI-LAUNCH-CONTEXT.md`
+
+The runner loads this complete suffix once when the agent process starts and does not refresh it during the session. Optional human operator instructions remain user context.
 
-Target `AGENTS.md`, compatible `CLAUDE.md`, and skills are loaded through
-OpenHands project context and progressive disclosure. The checked-in root
-`CLAUDE.md` is only a compact pointer to this development context; neither root
-file is a pod role instruction.
+Target skills are loaded explicitly through OpenHands skill context. Target and runner `AGENTS.md`, `AGENT.md`, or `CLAUDE.md` instruction files are human-facing development context and are not loaded as Senpai project context; the checked-in root `CLAUDE.md` links to this canonical guide.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md