diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8f84e07
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```sh
+bun install                              # install dependencies
+bun run check                            # Biome lint + format (run before committing)
+bun test                                 # run all tests
+bun test <path>                          # run a single test file
+bun run bundle                           # bundle all *-entry.ts files → dist/*.esm.js
+uncaged-workflow add <name> <bundle.esm.js>  # register a workflow bundle
+uncaged-workflow run <name>              # run a registered workflow
+```
+
+### One-time setup for docx-diff binary
+
+```sh
+cd /Users/yanjiayi/workspace/docx-diff && npm install && npm run build && npm link
+```
+
+The `@uncaged` scoped packages resolve from a private registry configured in `bunfig.toml` (`https://git.shazhou.work/api/packages/shazhou/npm/`).
+
+## Architecture
+
+This is a Bun monorepo (`workspaces: ["templates/*", "workflows"]`) for developing `@uncaged/workflow-runtime` workflows.
+
+**Two layers:**
+
+- `templates/<name>/` — pure data packages: `WorkflowDefinition` (roles + `ModeratorTable`), no agent binding. Exported from `src/index.ts`.
+- `workflows/` — binds a template's `WorkflowDefinition` to an `AdapterFn` and `ExtractFn`; each workflow instance is a `*-entry.ts` file that the bundle script turns into a single `dist/*.esm.js`.
+
+**Bundle script** (`scripts/bundle.ts`): scans `workflows/` for `*-entry.ts` files, bundles each with Bun into `dist/<stem>.esm.js` (ESM, Node target, no splitting). All `@uncaged/workflow-*` packages are kept external. Also emits a `.d.ts` shim per bundle.
+
+**Engine loop**: `ModeratorTable` routes from `START` → role → … → `END`. Each step: Adapter produces typed meta via the role's Zod schema; engine appends the step and selects the next role.
+
+**Core types** (from `@uncaged/workflow-runtime`):
+- `RoleMeta` — `Record<string, Record<string, unknown>>`: role name → meta shape
+- `RoleDefinition<Meta>` — `description`, `systemPrompt`, `schema` (Zod v4)
+- `WorkflowDefinition<M>` — `description` + `roles` + `ModeratorTable`
+- `ModeratorTable` — declarative, serializable routing table; maps `START`/role names to ordered transition lists (`check` + next role or `END`)
+- `AdapterFn` — receives system prompt + Zod schema, returns a `RoleFn`
+- `ExtractFn` — resolves structured data from a CAS content hash
+
+## Coding Conventions
+
+- **`type` not `interface`** — use type aliases everywhere.
+- **`T | null` not `?:`** — write nullable fields as `field: T | null`, not `field?: T`.
+- **`function` not `class`** — no classes except third-party requirements or `Error` subclasses.
+- **Named exports only** — no default exports. Workflow bundles must export `run` and `descriptor` by name.
+- **No `console.log`** — use structured logger in library code.
+- **No dynamic `import()`** — bundles must be statically analyzable; dynamic imports break hash and loading constraints.
+- **No `import()` in business code** — the only exception is the engine's own bundle loader.