cli-preference: jaq is not a drop-in for jq

spacecraft-cli-preference/SKILL.md

@@ -205,7 +205,7 @@ Read files with a plain file-view operation — each is short (typically 40–12
 | `ps`             | `procs` 🦀            | `references/procs.md`         | Colored, tree, TCP/UDP columns            |
 | `top` / `htop`   | `bottom` 🦀 (`btm`)   | `references/bottom.md`        | Graphs, network, processes                |
 | `cd` + history   | `zoxide` 🦀 (`z`)     | `references/zoxide.md`        | Shell init required                       |
-| `jq`             | `jaq` 🦀              | `references/jaq.md`           | Faster; near-identical syntax             |
+| `jq`             | `jaq` 🦀              | `references/jaq.md`           | Faster. **Not alias-safe** — no auto-vivification; use `pathfinder` for existing jq scripts |
 | `tar`/`zip`/`gz` | `ouch` 🦀             | `references/ouch.md`          | One command, all archive formats          |
 | `diff` (git)     | `delta` 🦀            | `references/delta.md`         | Configure as `core.pager` in `.gitconfig` |
 | `make`           | `just` 🦀             | `references/just.md`          | `Justfile`, not `Makefile`                |

spacecraft-cli-preference/references/jaq.md

@@ -24,9 +24,35 @@ Faster, near drop-in `jq` clone. Compatible with most `jq` filters, written in s
 3. Filter array: `jaq '.[] | select(.active)' users.json`
 4. Group and count: `jaq 'group_by(.kind) | map({kind: .[0].kind, n: length})'`
 5. Build object: `jaq -n --arg v 1.0 '{version: $v, generated: now}'`
-6. Slurp multiple files: `jaq -s 'add' a.json b.json`
+6. Slurp one file: `jaq -s 'add' a.json`
+   (`jaq -s … a.json b.json` slurps **per file** and runs the filter twice —
+   see Gotchas.)
 
 ## Gotchas
-- A handful of exotic `jq` features aren't supported — see `jaq`'s README for gaps.
-- Error messages differ from `jq`; adapt CI assertions accordingly.
-- No streaming parser (`--stream`); use `jq` for huge JSON blobs.
+**`jaq` is not a drop-in for `jq`, and `alias jq = jaq` will break scripts.**
+Use **Pathfinder** (`https://Pathfinder.SpacecraftSoftware.org/`) when existing
+jq scripts have to keep working; it translates the command line, supplies the
+missing builtins, and reports what it cannot repair. Measured against jq 1.8.1:
+
+- **No auto-vivification** — the one that actually bites. `jq` creates missing
+  containers along an assignment path; `jaq` errors.
+  `echo null | jaq '.a.b = 1'` → `cannot use null as iterable`, where `jq`
+  gives `{"a":{"b":1}}`. Every "build the object as you go" idiom breaks,
+  including `reduce … (null; .[$k] = …)`.
+- **Several input files are not one stream.** `jq` concatenates them; `jaq`
+  runs the whole filter once per file, so `jaq -s 'add' a.json b.json` prints
+  two results rather than one. Affects `-s`, `input` and `inputs`.
+- **Output-format flags are not last-wins.** `jq -c --tab` pretty-prints with
+  tabs; `jaq -c --tab` is compact.
+- **22 jq builtins are missing**, including `tostream`, `fromstream`, `IN`,
+  `INDEX`, `JOIN`, `builtins`, `input_filename` and `$__loc__`.
+- **9 jq flags are rejected** with `unknown flag`: `-a`, `--seq`, `--stream`,
+  `--stream-errors`, `--jsonargs`, `--unbuffered`, `-b`, `--argfile`, and the
+  attached `-Ldir` spelling.
+- `"a" * 0` is `null` (jq: `""`); `1 / 0` is `Infinity`, which is invalid JSON
+  on stdout (jq errors).
+- Error messages differ from `jq`; adapt CI assertions accordingly. The exit
+  **codes** do match jq in every case tested.
+
+`jaq` has one flag `jq` lacks: **`-i`/`--in-place` rewrites the input file**.
+Never pass an unrecognised flag through to it blindly.