diff --git a/roar/cli/templates/agents/SKILL.md.tmpl b/roar/cli/templates/agents/SKILL.md.tmpl
index 5301200..483247e 100644
--- a/roar/cli/templates/agents/SKILL.md.tmpl
+++ b/roar/cli/templates/agents/SKILL.md.tmpl
@@ -80,6 +80,9 @@ Workloads should NOT need to know which backend is active.
 
 ## Gotchas
 
+- **Clean git state is required.** `roar run` refuses to execute if the git working tree has uncommitted changes — including untracked files. There's no `--dirty` bypass; commit (or stash, or gitignore) first. Lineage ties to a commit, so this is by design.
+- **Add `.roar/` to `.gitignore` before your first run.** Otherwise it becomes an untracked change that trips the clean-tree check above on the next run. `roar init` prompts to add it; say yes. If you run `roar init -n` (skip) you'll need to add it yourself.
+- **Default config filters `/tmp`.** `ignore_tmp_files = true` in the generated `config.toml` silently drops any I/O under `/tmp`. If a run shows `in:0 out:0` or a missing `Inputs/Outputs` section and you're working under `/tmp`, that's why — move the workdir or edit `.roar/config.toml` to flip the filter. Other default filters hide system reads (`/sys`, `/etc`) and installed-package reads.
 - **Ray workers**: `ROAR_WRAP=1` is set on the driver but NOT on Ray workers. `ROAR_SESSION_ID` and `ROAR_JOB_ID` are propagated. Use those if a worker needs to detect provenance context.
 - **Osmo workers**: no env var propagation today.
 - **Don't make user code import roar** for tracking purposes — capture is transparent. The only exception is `from roar import require` for the abort-if-not-tracked guard.
diff --git a/roar/cli/templates/agents/agents_section.md.tmpl b/roar/cli/templates/agents/agents_section.md.tmpl
index c909462..e83c9d8 100644
--- a/roar/cli/templates/agents/agents_section.md.tmpl
+++ b/roar/cli/templates/agents/agents_section.md.tmpl
@@ -4,6 +4,8 @@ This project uses [roar](https://github.com/treqs/roar) to capture lineage for M
 
 - **Run scripts with provenance:** prefer `roar run <cmd>` over bare `<cmd>` (e.g. `roar run python train.py`).
 - **Don't modify code to use roar.** Capture is transparent. The exception: `from roar import require` at the top of a script aborts if it isn't being run under `roar run`.
+- **Clean git state is required.** `roar run` refuses to execute with uncommitted changes (including untracked files). No `--dirty` bypass. Make sure `.roar/` is in `.gitignore`.
+- **Avoid `/tmp` for workdirs.** Default config has `ignore_tmp_files = true`, which silently drops I/O under `/tmp` — a run there will show `in:0 out:0`.
 - **Inspect lineage:** `roar show <ref>`, `roar log`, `roar dag`. Add `--all` to `roar show` to disable truncation.
 - **Don't commit `.roar/`** — it's local lineage state.
 - **`roar --help` is the source of truth** for current command behavior.