feat: allow instruction_file to accept a list of files

[dgageot]

Agents often share a common preamble — coding conventions, tone guidelines, a project glossary — but each also needs its own role-specific instructions. Previously instruction_file accepted only a single path, so teams had to maintain one monolithic file per agent or work around the limitation with custom tooling.

This change extends instruction_file so it accepts either a single string (unchanged behaviour) or a list of strings. When multiple paths are given, their contents are concatenated in order separated by a blank line, letting you compose a shared preamble with per-agent specifics cleanly. A single-element list serialises back to scalar form, so existing configs and round-tripped YAML are unaffected. The new form is reflected in agent-schema.json (oneOf string or array), the docs, and a new example under examples/instruction_file.yaml with an accompanying examples/instructions/shared-preamble.md.

All existing path-safety rules apply to every entry in the list: absolute paths and .. traversal are rejected, and reads are confined with os.OpenRoot so symlinks cannot escape the config directory. List-form configs are local-file-only; OCI and URL sources are not supported (consistent with the existing single-file restriction). The configUsesInstructionFile OCI-push probe handles both string and list forms so pushed artifacts remain self-contained. The implementation lives in a new InstructionFiles type with custom YAML/JSON marshalers in pkg/config/latest/types.go; the resolution logic in pkg/config/config.go was refactored into a readInstructionFiles helper that uses a deferred root.Close to avoid leaking the os.Root handle. New tests cover list concatenation, missing files, per-entry traversal rejection, empty-entry rejection, and single-element scalar marshalling.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

[docker-agent]

[MEDIUM] MarshalYAML returns empty slice for zero-length InstructionFiles, bypassing omitempty

When instruction_file: [] is parsed from YAML, UnmarshalYAML correctly falls through the scalar path (can't decode a sequence into string) and calls list(&many), which succeeds with many = []string{} — giving a non-nil empty InstructionFiles{}. This non-nil empty value later reaches MarshalYAML:

func (f InstructionFiles) MarshalYAML() (any, error) {
    if len(f) == 1 {
        return f[0], nil
    }
    return []string(f), nil  // returns []string{} for len==0 — not nil
}

In go-yaml v3, omitempty on the struct field checks whether the value equals the zero value for its type before deciding to call MarshalYAML. For a named slice type, nil is zero but a non-nil empty slice is not — so go-yaml v3 will call MarshalYAML, receive []string{}, and serialize it as instruction_file: [] in the output YAML instead of omitting the field entirely.

resolveInstructionFiles skips agents with len(agent.InstructionFile) == 0 but does not normalize an empty slice to nil, so the empty InstructionFiles{} persists through OCI packaging and share push workflows.

Fix: add an early-return guard in MarshalYAML:

func (f InstructionFiles) MarshalYAML() (any, error) {
    if len(f) == 0 {
        return nil, nil
    }
    if len(f) == 1 {
        return f[0], nil
    }
    return []string(f), nil
}

[docker-agent]

[LOW] Empty string entry in instruction_file list causes confusing error; inconsistent with scalar handling

The scalar form instruction_file: "" is silently treated as absent (the unmarshal path explicitly sets *f = nil when one == ""). But an empty string inside a list — e.g. instruction_file: ["", "file.md"] — is not filtered during unmarshal, and later trips the path-safety check:

if !filepath.IsLocal(path) {   // filepath.IsLocal("") == false in Go ≥1.20
    return "", fmt.Errorf("instruction_file %q must be a local relative path …", path)
}

This produces the error: instruction_file "" must be a local relative path inside the config directory — which correctly rejects the input but gives no indication that the problem is an empty entry rather than a traversal attempt.

The inconsistency means a user who migrates from the scalar "" (silently ignored) to the list form [""] will get an unexpected error instead of the same no-op. Consider filtering out empty strings in unmarshal (same as the scalar branch does) and/or improving the error message to distinguish an empty path from a path-traversal attempt.

[dgageot]

Thanks for the review! Addressed both points in 1e0b633:

• [MEDIUM] empty slice bypassing omitempty: MarshalYAML/MarshalJSON now return nil/null for a zero-length InstructionFiles, so the omitempty tag drops the field entirely instead of emitting instruction_file: []. Verified that a config parsed from instruction_file: [] re-marshals without the field, so OCI packaging / share push stay clean.
• [LOW] empty entry in list: empty strings are now dropped on decode (new nonEmptyInstructionFiles helper), making the list form consistent with the scalar form where instruction_file: "" is treated as absent. instruction_file: [""] is now a no-op instead of failing the path-safety check.

Added tests: TestInstructionFileEmptyMarshalsAsNull, TestInstructionFileListDropsEmptyEntries, TestInstructionFileListAllEmptyIgnored. Build, tests, and golangci-lint all pass.

[aheritier]

👋 This PR has merge conflicts with the base branch. Please rebase or merge the latest base branch and resolve them. I've moved it to draft and added status/needs-rebase; it'll be picked back up automatically once the conflicts are cleared.

[docker-agent]

Assessment: 🟢 APPROVE

The implementation looks correct and well-structured. The custom YAML/JSON marshalers handle both scalar and list forms properly, the helper correctly applies path-safety rules (absolute path rejection, ... traversal, os.OpenRoot confinement) to every entry, the deferred root.Close avoids handle leaks, and the OCI push probe covers both string and list forms. Concatenation with a blank-line separator and single-element scalar round-tripping are correct.