diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..7164466
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality-gate:
+    name: Lint, typecheck, test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Enable Corepack before setup-node so its yarn cache step can resolve the
+      # pinned Yarn 4 (from package.json `packageManager`) and find the cache folder.
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Typecheck
+        run: yarn typecheck
+
+      - name: Test
+        run: yarn test
diff --git a/README.md b/README.md
index 39ed655..be8dffd 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,22 @@ yarn lint           # run ESLint (flat config) over the repo
 > The dev and preview servers are served under the `/chaiba/` base path (matching
 > the GitHub Pages deployment), so open `http://localhost:5173/chaiba/`.
 
+## Continuous integration
+
+Every push to `main` and every pull request runs the CI quality gate
+(`.github/workflows/ci.yml`) on Node 22 (LTS) with Yarn 4 via Corepack. The gate
+runs three checks and fails the build if any of them fail:
+
+```bash
+yarn install --immutable   # lockfile must be in sync (yarn.lock only)
+yarn lint                  # ESLint — fails on errors (warnings are non-blocking)
+yarn typecheck             # tsc --noEmit
+yarn test                  # Vitest unit suite
+```
+
+A PR cannot be merged green unless lint (no errors), typecheck, and the test
+suite all pass. Run the same checks locally before pushing to avoid a red CI.
+
 ## Deployment
 
 Pushes to `main` are built with Vite and published to GitHub Pages via