add doc-sandbox: answer from the installed program, not memory

The explainer for questions about a flag, a config key, a refusal, a
mechanism or a security boundary. ai-sandbox generates its own
Containerfile, entrypoint, squid config and netfilter rules from one
script, so the text of the program is the documentation of the version
the user will run: the skill sets a strict ground-truth order -- the
installed script and --help, then the repo docs, then the tests as the
executable spec -- and its own fact sheet last, overridden by all of
them.

scripts/locate.sh resolves that order on an arbitrary machine: the
installed script and its version, the source tree behind it (via
$AISB_REPO, the script's own parent, $PWD, the git root), the docs with
their line counts, and the config/state/cache locations.

references/source-map.md maps a question topic to the function, doc and
test that hold the answer, plus the vocabulary (split_target,
classify_allows, gate vs --no-gate vs --proxy, POL[]/P_*/OPT_*) and the
FAQ. The skill names which safe surface answers what: the --dry-run,
--print-entrypoint, --print-containerfile and --print-policy previews
build nothing and reach no registry, while inspect, doctor --deep,
build, update and gate up do change the machine and are not for an
explanation. It records the two honest exceptions rather than
overclaiming -- --print-policy ensures the home volume, and --no-gate
hits DNS.

Read-only by construction: no build, no container, no network call, and
it reads pi_config_bridge() rather than a models.json holding a live
key. Its worst failure mode is an invented flag, so the answer format
requires the real spelling, the source it came from, what the thing does
not do, and a plain "no" plus the closest real thing when the answer is
no.

LLM-Generated: true

.agents/skills/doc-sandbox/scripts/locate.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# locate.sh -- where the ground truth for an ai-sandbox question lives on THIS machine.
+#
+# Read-only, prints no secrets, starts nothing. Answers questions about ai-sandbox from the
+# program's own text and its docs, never from memory -- so first find them.
+#
+#   bash locate.sh
+
+set -uo pipefail
+
+section() { printf '\n== %s\n' "$1"; }
+note()    { printf '   %s\n' "$1"; }
+found()   { printf '   [x] %s\n' "$1"; }
+warn()    { printf '   [!] %s\n' "$1"; }
+
+BIN="$(command -v ai-sandbox 2>/dev/null || true)"
+[[ -n "$BIN" ]] || BIN="$(command -v ai-sandbox-autophase 2>/dev/null || true)"
+
+section "the program (the authority on flags and behaviour)"
+if [[ -n "$BIN" ]]; then
+  real="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
+  found "$real"
+  note "version: $("$BIN" version 2>/dev/null || printf 'unknown -- older than the version subcommand')"
+  note "flags for this exact build: $BIN --help"
+else
+  warn "ai-sandbox is not on PATH -- answer from the repository instead, and say so"
+fi
+
+# A candidate is the script itself, or a repo holding it (bin/ai-sandbox with README.md beside).
+SCRIPT=""
+[[ -n "$BIN" ]] && SCRIPT="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
+
+candidates=()
+[[ -n "${AISB_REPO:-}" ]] && candidates+=("$AISB_REPO")
+[[ -n "${SCRIPT:-}" ]] && candidates+=("$(dirname "$(dirname "$SCRIPT")")")
+candidates+=("$PWD" "$(git rev-parse --show-toplevel 2>/dev/null || true)")
+
+REPO=""
+for c in ${candidates[@]+"${candidates[@]}"}; do
+  [[ -n "$c" && -d "$c" ]] || continue
+  if [[ -f "$c/bin/ai-sandbox" && -f "$c/docs/threat-model.md" ]]; then REPO="$c"; break; fi
+done
+
+section "the source tree (the authority on why)"
+if [[ -n "$REPO" ]]; then
+  found "$REPO"
+  for f in README.md AGENTS.md docs/networking.md docs/threat-model.md docs/recipes.md bin/ai-sandbox bin/ai-sandbox-autophase; do
+    [[ -f "$REPO/$f" ]] && note "$(printf '%-32s %s lines' "$f" "$(wc -l < "$REPO/$f")")"
+  done
+  [[ -d "$REPO/tests" ]] && note "tests/ -- the executable spec: unit/ needs no containers, e2e/ runs real ones"
+  [[ -z "$BIN" ]] && note "not installed, but this tree runs: $REPO/bin/ai-sandbox --help"
+  note "if the installed script and this tree differ, say which one you read"
+else
+  note "no repository found (tried \$AISB_REPO, the installed script's parent, \$PWD, the git root)"
+  note "the installed script alone answers most questions: it is one file, and it generates"
+  note "the Containerfile, the entrypoint and the squid config from itself"
+fi
+
+section "read the machine, or read the script"
+note "safe, deterministic, no build / container / state / registry:"
+note "  ai-sandbox --help                      every flag, this version"
+note "  ai-sandbox version"
+note "  ai-sandbox --dry-run                   the exact podman invocation, secret values redacted"
+note "  ai-sandbox --print-policy              effective policy as key=value -- but it also ensures the"
+note "                                       home volume exists, so it needs podman on the host"
+note "  ai-sandbox --print-entrypoint          the enforcement script baked into the image"
+note "  ai-sandbox --print-containerfile       the generated Containerfile"
+note "asks the machine now (may reach the registry, starts nothing): ai-sandbox inspect"
+note "touches the host: doctor [--deep], build, update, gate up, clean, and any real run"
+
+section "state a run leaves behind"
+note "config:  ${AISB_CONFIG_DIR:-$HOME/.config/ai-sandbox}/{config,allow}"
+note "state:   ${AISB_STATE_DIR:-$HOME/.local/state/ai-sandbox}/log   (every run, no secret values)"
+note "cache:   ${AISB_CACHE_DIR:-$HOME/.cache/ai-sandbox}/base/       (the recorded base digests)"
+note "repo:    ./.ai-sandbox/{config,allow}"