diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..817e17f
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  rust-assembler:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: _assembler
+      - run: cd _assembler && cargo test --release
+
+  rust-primitives:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: _primitives/_rust
+      - run: cd _primitives/_rust && cargo test --workspace --release
+
+  ts-packages:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node: ['18', '20', '22']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: cd _ts_packages && npm ci
+      - run: cd _ts_packages && npm run build --workspaces
+      - run: cd _ts_packages && npm test --workspaces --if-present
+
+  install-dry-run:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install hard deps (Ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update && sudo apt-get install -y jq pandoc
+      - name: Install hard deps (macOS)
+        if: matrix.os == 'macos-latest'
+        run: brew install jq pandoc
+      - run: bash -n install.sh
+      - run: ./install.sh --no-execute --profile=minimal
+      - run: ./install.sh --no-execute --profile=dev
+      - run: ./install.sh --no-execute --profile=full
+
+  shell-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y shellcheck
+      - name: shellcheck (advisory)
+        run: find hooks _primitives -name '*.sh' -exec shellcheck -S warning {} +
+        continue-on-error: true  # warnings are advisory initially
+
+  genesis-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: _primitives/_rust
+      - run: cd _primitives/_rust && cargo build --release -p genesis-scan
+      - run: ./_primitives/_rust/target/release/genesis-scan --path . --format=human --exit-on-hit
diff --git a/.gitignore b/.gitignore
index 171358e..552cbd9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,7 @@
 _primitives/_rust/target/
 **/target/
 .DS_Store
+
+# Agent worktrees — ephemeral orchestrator scratch dirs, never commit.
+.claude/worktrees/
+**/.claude/worktrees/