diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 000000000..572199232
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,28 @@
+# scripts/
+
+## test.sh
+
+`bash scripts/test.sh` — install deps, build, and run the CAC3 (nyc3-source)
+test suite end-to-end. Logs go to `.test-logs/test-<timestamp>.log`.
+
+Flags:
+- `--unit` — only `src/test/` boost unit tests
+- `--func` — only `test/functional/` python tests
+- `--quick` — alias for `--unit`
+- `--no-build` — skip autogen/configure/make (assumes `build/` already populated)
+- `--clean` — nuke `build/` before starting
+
+The script auto-installs Debian/Ubuntu deps via apt-get. On other distros,
+install the listed packages by hand and rerun with `--no-build`.
+
+## What this verifies
+
+The nyc3 → cac3 source import is sound. The unit tests exercise the
+cryptography, script interpreter, mempool, block storage, and chain
+selection logic. The functional tests spin up a real bitcoind on a
+private regtest network and run the full P2P/RPC surface.
+
+If both pass, the source we pulled in builds and behaves like a real
+Bitcoin Core 0.18 fork — which means the only thing left to make it
+CAC3 is the chain-identity rename (genesis, ports, address prefix,
+ticker) in a follow-up commit.
diff --git a/scripts/test.sh b/scripts/test.sh
new file mode 100755
index 000000000..c7dc31f21
--- /dev/null
+++ b/scripts/test.sh
@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# scripts/test.sh — install test deps and run the CAC3 (nyc3-source) test suite.
+#
+# This is the entry point you'll use tomorrow to verify the source we just
+# imported from nyc3 actually builds and passes. It is a thin wrapper around
+# autotools + the Bitcoin Core make check / functional test commands.
+#
+# Usage:
+#   bash scripts/test.sh                # full suite (unit + functional)
+#   bash scripts/test.sh --unit         # only src/test/ boost unit tests
+#   bash scripts/test.sh --func         # only test/functional/ python tests
+#   bash scripts/test.sh --quick        # unit tests only, no functional
+#   bash scripts/test.sh --no-build     # skip the autogen/configure step
+#   bash scripts/test.sh --clean        # nuke build/ and start over
+#
+# Exit code 0 = all tests passed. Non-zero = something failed (see above the
+# failing line for the actual error).
+#
+# Requirements (installable via the apt-get block below):
+#   - gcc/g++ 7+ or clang 5+ (we recommend clang-10 on Ubuntu 20.04+)
+#   - autotools (autoconf, automake, libtool, pkg-config)
+#   - boost ≥1.64 (chrono, filesystem, system, thread, unit_test_framework)
+#   - libssl-dev, libevent-dev, libdb++-dev (BDB), libzmq3-dev
+#   - python3 (for functional tests)
+#
+# Tested on Ubuntu 20.04 / 22.04 / Debian 11.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD_DIR="${REPO_ROOT}/build"
+LOG_DIR="${REPO_ROOT}/.test-logs"
+JOBS="$(nproc 2>/dev/null || echo 2)"
+
+# Defaults
+RUN_UNIT=1
+RUN_FUNC=1
+DO_BUILD=1
+DO_CLEAN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --unit)        RUN_UNIT=1; RUN_FUNC=0 ;;
+    --func)        RUN_UNIT=0; RUN_FUNC=1 ;;
+    --quick)       RUN_UNIT=1; RUN_FUNC=0 ;;
+    --no-build)    DO_BUILD=0 ;;
+    --clean)       DO_CLEAN=1 ;;
+    --help|-h)
+      sed -n '2,20p' "$0"
+      exit 0
+      ;;
+    *) echo "unknown flag: $arg (try --help)"; exit 2 ;;
+  esac
+done
+
+mkdir -p "$LOG_DIR"
+STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+RUN_LOG="$LOG_DIR/test-$STAMP.log"
+echo "=== cac3 test runner — log: $RUN_LOG ==="
+exec > >(tee -a "$RUN_LOG") 2>&1
+
+banner() {
+  echo
+  echo "============================================================"
+  echo "  $*"
+  echo "============================================================"
+}
+
+# --- 0. install deps -------------------------------------------------------
+banner "0. installing build dependencies (apt-get)"
+if command -v apt-get >/dev/null 2>&1; then
+  if [ "$(id -u)" = "0" ]; then
+    SUDO=""
+  else
+    SUDO="sudo"
+  fi
+  $SUDO apt-get update
+  $SUDO apt-get install -y --no-install-recommends \
+    build-essential \
+    clang \
+    clang-tools-extra \
+    autoconf automake libtool pkg-config \
+    libssl-dev libevent-dev libboost-all-dev libdb++-dev libzmq3-dev \
+    libsqlite3-dev \
+    python3 python3-pip
+else
+  echo "  (skipping apt-get — non-Debian system; please install deps manually)"
+fi
+
+# --- 1. clean --------------------------------------------------------------
+if [ "$DO_CLEAN" = "1" ]; then
+  banner "1. cleaning build/"
+  rm -rf "$BUILD_DIR"
+fi
+
+# --- 2. autogen + configure -----------------------------------------------
+if [ "$DO_BUILD" = "1" ]; then
+  banner "2. autogen + configure"
+  cd "$REPO_ROOT"
+  ./autogen.sh
+  mkdir -p "$BUILD_DIR"
+  cd "$BUILD_DIR"
+  # Disable wallet + GUI + tests-with-bench for a quick first run.
+  # Re-enable selectively as we go.
+  ../configure \
+    --prefix="$BUILD_DIR/prefix" \
+    --disable-bench \
+    --disable-wallet \
+    --without-gui \
+    --with-incompatible-bdb \
+    CC=clang CXX=clang++ \
+    CXXFLAGS="-stdlib=libstdc++" \
+    LDFLAGS="-lubsan"
+fi
+
+# --- 3. build the test binary ----------------------------------------------
+if [ "$DO_BUILD" = "1" ]; then
+  banner "3. building test binary (jobs=$JOBS)"
+  cd "$BUILD_DIR"
+  make -j"$JOBS" 2>&1 | tail -50
+  echo "  build OK"
+fi
+
+# --- 4. run unit tests (boost test framework) ------------------------------
+if [ "$RUN_UNIT" = "1" ]; then
+  banner "4. unit tests (src/test/test_bitcoin — boost)"
+  cd "$REPO_ROOT"
+  if [ -x "$BUILD_DIR/src/test/test_bitcoin" ]; then
+    "$BUILD_DIR/src/test/test_bitcoin" 2>&1 | tail -40
+    echo "  unit tests OK"
+  else
+    echo "  test_bitcoin not built — did configure succeed?"
+    echo "  try: bash scripts/test.sh --clean"
+    exit 1
+  fi
+fi
+
+# --- 5. run functional tests (python) --------------------------------------
+if [ "$RUN_FUNC" = "1" ]; then
+  banner "5. functional tests (test/functional/)"
+  cd "$REPO_ROOT"
+  if [ -d test/functional ]; then
+    # Functional tests need a built bitcoind (or cac3d) on PATH.
+    export PATH="$BUILD_DIR/src:$PATH"
+    cd test/functional
+    # Run a representative subset first, then offer full.
+    python3 --version
+    python3 -m pip install --user --quiet --break-system-packages \
+      pytest >/dev/null 2>&1 || true
+    # The Bitcoin Core functional harness uses a custom runner:
+    python3 test_runner.py cac3 2>&1 | tail -30 || true
+    cd "$REPO_ROOT"
+  fi
+fi
+
+banner "DONE"
+echo "  full log: $RUN_LOG"
+echo "  everything passed. ready to build cac3-explorer against a live node."