diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..0f8c71b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,47 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deterministic:
+    name: deterministic-${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Run full tests
+        if: runner.os == 'Linux'
+        run: >-
+          uvx --python 3.13 --from pytest==9.1.1
+          --with pyyaml==6.0.3 --with sqlite-vec==0.1.9 pytest -q
+
+      - name: Run macOS portable tests
+        if: runner.os == 'macOS'
+        run: >-
+          uvx --python 3.13 --from pytest==9.1.1
+          --with pyyaml==6.0.3 --with sqlite-vec==0.1.9
+          pytest -q -k "not test_index_rebuild_installs_and_loads_sqlite_vec_when_available"
+
+      - name: Validate skill packages
+        run: bin/work-bundle-skill validate
diff --git a/README.md b/README.md
index e97d20a..2903dd7 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,28 @@
 # work-bundle
 
+[![CI](https://github.com/Ldsystem/work-bundle/actions/workflows/ci.yml/badge.svg)](https://github.com/Ldsystem/work-bundle/actions/workflows/ci.yml)
+![Python 3.13](https://img.shields.io/badge/Python-3.13-3776AB?logo=python&logoColor=white)
+
 Toolkit source for WorkBundle skills, rules, references, and deterministic helper code.
 
+## Ecosystem
+
+WorkBundle owns orchestration contracts, workspace authority, durable knowledge,
+and acceptance flow. [Execution Flow](https://github.com/Ldsystem/execution-flow)
+is a separate, optional TypeScript repository that supplies provider-neutral
+executor selection and ACP delegation without taking over WorkBundle
+orchestration.
+
+The recommended local layout for developing both repositories is a
+multi-repository workspace:
+
+```text
+work-bundle-workspace/
+├── .work-bundle/       # portable workspace authority and runtime artifacts
+├── work-bundle-main/   # this toolkit repository
+└── execution-flow/     # the independent Execution Flow repository
+```
+
 WorkBundle distinguishes four roots:
 
 - `work_bundle_root` — this installed toolkit source.
@@ -43,3 +64,10 @@ bin/work-bundle-skill list
 bin/work-bundle-skill validate
 bin/install-work-bundle-skills --dry-run
 ```
+
+Run the deterministic repository gate with isolated dependencies:
+
+```bash
+uvx --python 3.13 --from pytest==9.1.1 --with pyyaml==6.0.3 --with sqlite-vec==0.1.9 pytest -q
+bin/work-bundle-skill validate
+```