diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
new file mode 100644
index 0000000..beb7b9c
--- /dev/null
+++ b/.github/workflows/ci-docs.yml
@@ -0,0 +1,36 @@
+# Sentinel workflow for docs-only PRs.
+#
+# When a PR touches only *.md / docs / README files, the main CI workflow
+# (ci.yml) is skipped entirely via paths-ignore. GitHub does NOT automatically
+# mark required checks as passing when a workflow is never triggered — it only
+# does so when a workflow is triggered but individual jobs are skipped.
+#
+# This workflow fills that gap: it runs only for docs-only PRs and immediately
+# satisfies the two required checks ("CI check" and "Analyze
+# (javascript-typescript)") so branch protection does not block the merge.
+#
+# For mixed PRs (docs + code), both this workflow and ci.yml trigger.
+# All checks pass, no conflict.
+
+name: CI (docs-only)
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - "docs/**"
+      - "examples/**/README.md"
+
+jobs:
+  check:
+    name: CI check
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Docs-only PR — full CI skipped"
+
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Docs-only PR — CodeQL skipped"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a358a8f..f6de2af 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,7 +4,7 @@
 # The check job aggregates all results for branch protection.
 #
 # Docs-only PRs (*.md, docs/**, examples/**/README.md) skip the entire workflow via
-# paths-ignore; GitHub marks the required status checks as passing automatically.
+# paths-ignore. Required checks for those PRs are satisfied by ci-docs.yml.
 #
 # The first job defines YAML anchors (&checkout, &setup-node-22, &install)
 # on its setup steps; subsequent jobs alias them to avoid repetition.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4376c61
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,60 @@
+# OpenDecree TypeScript SDK — Claude Context
+
+## Overview
+
+TypeScript SDK for the OpenDecree configuration service. Wraps the gRPC API with a typed
+client, field-watching subscriptions, version compatibility checks, and optional JWT rotation.
+
+## Tech Stack
+
+| Concern | Tool |
+|---------|------|
+| Language | TypeScript (strict) |
+| Runtime | Node.js 22+ |
+| Transport | @grpc/grpc-js |
+| Code generation | ts-proto via buf (Docker) |
+| Lint / format | Biome |
+| Tests | Vitest |
+| Build | tsc |
+
+## Development
+
+### Prerequisites
+
+Node.js 22+, Docker (for proto generation), npm.
+
+### Key Commands
+
+```bash
+npm run generate        # regenerate proto stubs (buf + Docker)
+npm run pre-commit      # biome check + typecheck + unit tests
+npm run test            # vitest run (unit)
+npm run test:integration # integration tests against live server
+npm run build           # tsc emit to dist/
+```
+
+### Layout
+
+```
+src/
+├── generated/    # generated proto stubs (committed)
+├── client.ts     # ConfigClient
+├── watcher.ts    # ConfigWatcher
+├── compat.ts     # server version checks
+└── ...
+test/             # unit tests
+integration/      # integration tests (live server)
+```
+
+## Coding Guidelines
+
+See [coding-guidelines.md](https://github.com/opendecree/decree/blob/main/docs/development/coding-guidelines.md)
+for the shared philosophy (vanilla principle, minimal deps) and the TypeScript-specific section
+(zero runtime deps beyond grpc-js, strict TS flags, Biome enforcement).
+
+## Conventions
+
+- Only runtime dependency: `@grpc/grpc-js`
+- Generated proto stubs committed under `src/generated/`
+- `SUPPORTED_SERVER_VERSION` generated from `package.json` via `scripts/gen-version.mjs`
+- Apache 2.0 license