docs: input-form decision rule + @- heredoc as the hook-safe path

docs/input-forms.md

@@ -2,6 +2,18 @@
 
 Three ways to pass arguments to supertool ops.
 
+## Which form? {#which-form}
+
+Pick by the shape of your content, not by habit:
+
+| Use | When | Why |
+| --- | --- | --- |
+| **Colon-CLI** | Short, single-line content with no `:` / quotes / newlines | Zero ceremony — it's just the op string |
+| **`@-` heredoc** | Multi-line / quoted / colon-bearing content, **one** op, nothing to keep | No file written; the command line starts with `./supertool`, so it survives enforced or autonomous runs that block bare shell builtins (`cat`, `echo`, …) |
+| **`@file`** | Same messy content, but you want to **re-run, batch, or diff** it | The payload is a durable artifact. Write it with an editor or your harness's file-write tool — **not** `cat > file`, which puts a blocked builtin at the start of the line under enforcement |
+
+The trap to avoid: writing a payload with `cat > .max/x.json <<'EOF'` and then reading it back. That line *starts* with `cat`, so an enforced/autonomous run flags it — and it forces hand-escaped `\n` JSON. If you need a single edit, pipe the heredoc straight into `@-`; if you need the file, write it with a tool, not `cat`.
+
 ## Colon-CLI (default)
 
 Most ops take arguments via `:` — `read:PATH:OFFSET:LIMIT`, `grep:PATTERN:PATH:LIMIT`. When content itself contains colons (code, SQL, timestamps), switch to `:::` triple-colon separators: `edit:::OLD:::NEW:::PATH`.

docs/operations/edits.md

@@ -72,7 +72,17 @@ When `old` or `new` spans multiple lines or contains characters that clash with
 { "old": "return false;", "new": "return true;", "path": "src/app/Foo.py" }
 ```
 
-Use `@-` to pipe from stdin instead of a file.
+Use `@-` to pipe from stdin instead of a file — a heredoc keeps the whole edit in one command with nothing written to disk, and a TOML body takes raw multi-line code with no escaping:
+
+```bash
+./supertool 'edit:@-' <<'EOF'
+path = "src/app/Foo.py"
+old = '''return false;'''
+new = '''return true;'''
+EOF
+```
+
+Because the line starts with `./supertool` (not `cat`/`echo`), this is the form to reach for under enforced or autonomous runs that block bare shell builtins. See [Which form?](../input-forms.md#which-form) for choosing between colon-CLI, `@-`, and `@file`.
 
 ### `batch:@file` — mixed ops in one round-trip