tools/INDEX.md

@@ -17,3 +17,35 @@ gets a Soul pass before merge.
 | `tools/test-tools.sh` | Local fixture check of the parsers and the summary over `tools/fixtures/logs` (real cargo and mutation logs, plus hand-written dotnet, vitest, jest, pytest, exit-0-but-failed and no-verdict logs), and of the mutation runners' host drivers and container halves (`tools/mutation-table.sh`, `tools/cargo-mutants.sh`) under a mock docker, a fake `cargo mutants` and real slot locks. Run it before merging a change to the scripts above. | whoever changes those scripts | `SKILL.md` (Shared tools) |
 | `tools/context-pack.py` | `py -3 tools/context-pack.py <spec file or -> <worktree> [--since <sha>] [--only <k>\|r<k>[,...]] [--max-lines <n>]`. Carries a cut_spec's `file_changes` and `reads` anchors (read rows `r<k>`; a read absent at base is MISSING) from the spec's base to the worktree by `git diff` hunks (the working tree included) and prints one header, a status table (SAME, MOVED, TOUCHED, RENAMED, NEW, GONE, OUT_OF_RANGE, UNRESOLVED, MISSING, plus SYMBOL_MISSING when an anchor's `symbol` is absent from its window) and windows of at most 100 lines numbered in worktree lines, then one capped caller list per symbol (`git grep`, hits outside the windows), within `--max-lines` (800). Exit 3 when an anchor cannot be carried, 4 when the spec is unreadable. The spec is the document `huginn view --raw <cut_spec id>` prints, saved to a file or piped to `-`; context-pack never fetches it, and an Unavailable from huginn is the caller's one retry. `--since <sha>` re-prints only the windows edited since that commit. Standard library plus git; writes nothing. | Hands, Soul, Imagination | `references/briefs.md` (Imagination map, Hands, Soul), `SKILL.md` (step 1) |
 | `tools/bloom-sheet/bloom_sheet.py` | `bloom-sheet notes.md -o sheet.png [--visitor a.svg]...`: a markdown document as one neon A4 page. The first top-level heading is the title, every other heading a card sized by its text; a plant grows through what's left, and each SVG visitor gets a disc it grows around and is drawn with the plant's pen, so it must be flat strokes or fills that touch; large fills become a wash and a heavy outline. PDF or PNG, about 2.5 minutes. `grow.py` owns the plant, `page.tex` the look, `test_visitors.py` what a visitor may be. | Minds and Self, for info renders | the `bloom-sheet` skill; `bloom-sheet` on Yggdrasil's PATH |
+
+## From a Self seat on Yggdrasil
+
+A Mind's Self run reads these scripts from a read-only, `noexec` tmpfs mount of
+the skill, and holds no Docker socket and no `ygg` ssh alias. So:
+
+- `tools/<script>.sh` as a command fails `Permission denied` whatever its git
+  mode; `noexec` ignores the exec bit. Run a script as `bash tools/<script>.sh`;
+  of the shared scripts, `wait-on.sh` is the one that is useful this way.
+- `tools/stopgap/ygg-verify.sh`, `tools/cargo-mutants.sh` and
+  `tools/mutation-table.sh` drive a remote `sudo docker` over `ssh ygg`
+  (`ygg-verify.sh` from line 280: the `ssh` calls, `sudo docker` at 321 and 410). Through `bash` they still stop at `Could not resolve
+  hostname ygg`. They are for the operator's workstation, or a seat that holds
+  Docker. Do not widen a seat to make them run.
+- `cargo-mutants` need not be on PATH for those scripts: the `rust` image
+  installs it. For a Self, install it once into the workspace, which is
+  writable and executable, and run it natively on the range:
+
+  ```
+  cargo install --locked cargo-mutants --root "$PWD/tools-bin"   # 27.1.0 built clean
+  PATH="$PWD/tools-bin/bin:$PATH"
+  git -C <repo> diff <base> <rev> > "$PWD/range.diff"      # absolute: the next line changes directory
+  cd <repo>/<workspace-dir> && cargo mutants --in-diff "$OLDPWD/range.diff" --list   # the mutants
+  cargo mutants --in-diff "$OLDPWD/range.diff" -j1 -- <test filter>                  # run them
+  ```
+
+  The diff is taken at the workspace root and `--in-diff` paths match relative to
+  it (see `tools/cargo-mutants.sh` header). A native run is a plain `cargo
+  mutants`: no per-file filter stage, no confirm stage, no slots, no CPU or memory
+  cap (set `CARGO_BUILD_JOBS`, and `-j1`; point `CARGO_TARGET_DIR` and `TMPDIR` at a disk with
+  room, since cargo-mutants copies the tree to `TMPDIR` and a small run took 2.3 GB), and its survivors are not confirmed on
+  the full suite. Run survivors again unfiltered before reporting them MISSED.