copilot-setup-steps: add Nix dev shell setup, CI cache restore, and Copilot instructions

.github/copilot-instructions.md

@@ -0,0 +1,37 @@
+# Copilot Instructions
+
+For full development guidance, see [AGENTS.md](../AGENTS.md).
+
+## Environment Setup
+
+This repository uses a [Nix](https://nixos.org/) dev shell to provide the
+OCaml toolchain (`ocaml`, `dune`, `opam`, `ocamlformat`, etc.).  The shell is
+**not** activated automatically, so every command must be prefixed with
+`nix develop -c`.
+
+### First-time setup
+
+On a fresh checkout (or after the `_boot/` directory has been removed), run
+bootstrap once before anything else:
+
+```bash
+nix develop -c make bootstrap
+```
+
+This builds `_boot/dune.exe`, the seed binary that Dune uses to build itself.
+It is slow but only needed once per environment.
+
+## Common Commands
+
+All commands from [AGENTS.md](../AGENTS.md) must be wrapped with
+`nix develop -c`:
+
+```bash
+nix develop -c dune build @check          # Quick build (recommended)
+nix develop -c dune build @install        # Full build
+nix develop -c dune runtest dir/          # Run tests in a directory
+nix develop -c dune runtest dir/test.t    # Run a specific cram test
+nix develop -c dune fmt                   # Auto-format code (run before committing)
+nix develop -c dune promote               # Accept test output changes (ask user first)
+nix develop -c make dev                   # Full build (bootstraps if necessary)
+```

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,40 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy
+# validation, and allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: nixbuild/nix-quick-install-action@v34
+
+      - name: Restore Nix cache
+        uses: nix-community/cache-nix-action@v7
+        with:
+          primary-key: nix-${{ runner.os }}-${{ github.job }}--${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: |
+            nix-${{ runner.os }}-${{ github.job }}--
+            nix-Linux-nix-test--
+          gc-max-store-size-linux: 2G
+          save: false
+
+      - name: Enter Nix dev shell
+        run: nix develop -c true