feat(config): support external instruction files via instruction_file

[Sayt-0]

Summary

Adds an optional instruction_file field on agent config so an agent's instruction can live in its own file (relative to the config file's directory) instead of being inlined in the YAML. This separates infrastructure configuration from behavioral content, which keeps version-control diffs focused, reduces merge conflicts on shared configs, and avoids YAML syntax risk when editing long prompts.

Scope is Option 1 (local file references) from the issue. The inline instruction field stays fully supported and is not deprecated.

agents:
  coordinator:
    model: openai/gpt-5-mini
    description: Routes work between specialist agents
    instruction_file: instructions/coordinator.md

Acceptance criteria

Criterion	Status	Notes
instruction_file parameter supported	yes	New field on the latest AgentConfig
Relative paths (relative to config file)	yes	Resolved against Source.ParentDir()
File content loaded at startup	yes	Resolved in config.Load, between migration and validation
Clear error messages if file not found	yes	Errors name the agent and the path
Backward compatible with inline instruction	yes	Both fields supported; setting both is rejected
Documentation updated with examples	yes	New docs section plus a runnable example
Tests cover file loading scenarios	yes	See test list below

Design decisions

• Resolution point. config.Load is the single choke point for every consumer (run, teamloader, OCI push, sandbox kit), so resolution happens there. The whole pipeline only ever sees the inlined Instruction; no downstream change is needed.
• Self-containment. After reading the file into Instruction, InstructionFile is cleared. This keeps the in-memory config self-contained and is required for the marshalling round-trip test (TestParseExamplesAfterMarshalling reloads via a parentless bytes source).
• Path safety. The reference must be a local relative path inside the config directory. Absolute paths and .. traversal are rejected via filepath.IsLocal, and reads are confined with os.OpenRoot (TOCTOU-safe, blocks symlink escapes). This mirrors the existing HCL file() helper and fileSource.Read.
• Mutual exclusivity. instruction and instruction_file cannot both be set.
• Parentless sources. OCI/URL/bytes sources have no directory to resolve against, so instruction_file is rejected there with a clear message. share push re-serializes the resolved config when instruction_file is used, so pushed artifacts inline the contents and stay self-contained.

Files

File	Change
pkg/config/latest/types.go	New InstructionFile field (latest config only; v0..v10 frozen)
pkg/config/config.go	resolveInstructionFiles called from Load
agent-schema.json	instruction_file added to the AgentConfig definition
pkg/oci/package.go	Re-serialize resolved config when instruction_file is used
examples/instruction_file.yaml, examples/instructions/*.md	Runnable coordinator/specialist example
pkg/config/instruction_file_test.go, pkg/oci/package_test.go	Tests
docs/configuration/agents/index.md	External Instruction Files section plus reference row

Test coverage: resolution from a relative path, file in a subdirectory, missing file, .. traversal rejected, absolute path rejected, symlink escape rejected, mutual exclusivity, parentless source rejected, empty-string treated as unset, and OCI push inlining (loads from the pushed bytes without the local file).

Validation

• golangci-lint run ./pkg/config/... ./pkg/oci/... reports no issues.
• go build ./... passes (the lint/ tooling module needs a network fetch unavailable in the sandbox and is unrelated).
• pkg/config and pkg/oci suites pass. The only failures in the local run are TestURLSource_Read_RejectsLocalAddresses, which are network-dependent SSRF tests unrelated to this change (they time out instead of rejecting because outbound network is blocked in the sandbox).

Possible follow-up

Option 2 from the issue (instruction_ref for OCI artifact references) is not included here and can be added later if maintainers want remote versioning.

Closes #1666

[docker-agent]

Assessment: 🟢 APPROVE

The instruction_file feature is well-implemented. The security design is sound:

• filepath.IsLocal provides a first-pass rejection of .. traversal and absolute paths
• os.OpenRoot confines reads to the config directory, blocking symlink escapes at the OS level (TOCTOU-safe)
• Parentless sources (OCI/URL/bytes) are correctly rejected with clear error messages
• Mutual exclusivity between instruction and instruction_file is correctly enforced
• The OCI push re-serialization path correctly inlines resolved instructions before pushing

Two hypotheses about the OCI re-serialization path were investigated and dismissed:

1. HCL + instruction_file: An HCL source fails at the initial yaml.Unmarshal version-probe (line 43–45), returning an explicit error before configUsesInstructionFile is ever called — no silent bypass.
2. goccy/go-yaml type assertion: goccy/go-yaml v1.19.2 decodes string-keyed YAML mappings as map[string]interface{}, so the probe["agents"].(map[string]any) assertion succeeds correctly for valid YAML configs.

One low-severity observation (not a bug): os.OpenRoot(parentDir) is called inside the per-agent loop. Opening the directory root once before the loop and reusing it for all agents would be slightly more efficient, but this is a style/performance note rather than a correctness issue and does not warrant blocking the PR.