# Templates and Examples

Two directories ship under `config/` in the repo:

- `examples/agent-templates/` — minimal pattern templates. Each one demonstrates one deployment pattern with the smallest YAML that exercises it. Copy-and-adapt is the intended workflow.

- `examples/agents/` — concrete real-world configs that document specific operator decisions (e.g. `newbie-docker.yaml` carries the Hawthorne-effect-free design notes from the 2026-04-12 contamination incident).

Both directories are validated by `tests/test_templates_v3_valid.py`. Every YAML must round-trip through `load_config` cleanly; the SLURM template additionally renders a valid sbatch script so YAML-key drift from `SlurmSpec` / `SlurmHooks` fails loudly in CI rather than at a user’s first `sac agent start`.

## Pattern Templates

Template | Pattern | When to use
--- | --- | ---
`apptainer.yaml` | claude-session inside Apptainer SIF | Default. HPC + reproducibility. F-CS17 made sac container-only; this is the canonical pattern.
`ssh.yaml` | remote agent via SSH | Cross-machine fleet member. `sac --on <peer>` (F-CS12) dispatches across hosts; the per-agent `dot_claude/` directory is rsync’d to the remote at start.

MCP tool wiring is no longer a separate template — drop a `.mcp.json` into the agent’s `dot_claude/` directory and it’ll be merged into `<workdir>/.mcp.json` at start (F-DC1).

## Instantiating a Template

The v3 loader uses `dir-as-SSoT` — the agent name is derived from the parent directory of the YAML, not from a `metadata.name` field. To instantiate:

    mkdir -p ~/.scitex/agent-container/agents/my-agent
    cp examples/agent-templates/apptainer.yaml \\
       ~/.scitex/agent-container/agents/my-agent/spec.yaml
    # Optionally add a dot_claude/ sibling with CLAUDE.md / .mcp.json /
    # .env / state.md / commands/ / skills/ / hooks/ (all optional).
    sac agent start my-agent

## Examples

Example | What it documents
--- | ---
`newbie-docker.yaml` | Hawthorne-effect-free naive-user simulation. Zero skills, zero fleet identity, `mount_host_claude: false`, `network: bridge` (not `none` — DNS blocking caused 3-min/call retry loops). Disposable: `restart.policy: never`.
`researcher-opus.yaml` | Opus-powered researcher with `restart.policy: on-failure`, backoff tuned for long-running research sessions.