@@ -0,0 +1,8 @@
+# Determinism is the point of this project, and the golden fixtures are
+# compared byte-for-byte. A Windows checkout rewriting LF -> CRLF would break
+# them on that platform only, so line endings are pinned everywhere.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.ico binary
@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # OPUS_SPEC §3.7: Python 3.12 / 3.13 x Linux, macOS, Windows.
+  # 3.12 is the strict floor -- do not add 3.10/3.11 back.
+  test:
+    name: pytest (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      # The coverage gate (100% line AND branch) lives in pyproject.toml.
+      - name: Run tests with coverage gate
+        run: poetry run pytest --cov --cov-branch
+
+  quality:
+    name: types, lint, codegen drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      - name: mypy --strict
+        run: poetry run mypy --strict n8n_iac
+
+      - name: ruff
+        run: poetry run ruff check n8n_iac tests
+
+      # The async facade is committed generated code; this fails if it was
+      # hand-edited or if the sync source moved without regenerating.
+      - name: Async facade is regeneration-stable
+        run: poetry run python -m n8n_iac.client._async_codegen --check
@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+.nox/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# n8n-iac runtime artifacts: deployment state binds uids to a specific
+# instance's workflow ids. It is environment-local and must never be shared.
+.n8n-iac-state.json
+*.n8n-iac-state.json
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and any contributor) working in this repository.
+
+`n8n_iac` is an infrastructure-as-code SDK for n8n: it models workflows as typed Python,
+compiles them to wire-exact n8n JSON through a deterministic pipeline, validates them offline,
+and deploys them with a Terraform-shaped plan/apply lifecycle.
+
+---
+
+## Source of Truth
+
+Two specifications define **all** architecture. Code exists to implement them, not to
+reinterpret them.
+
+- [`FABLE_SPEC.md`](FABLE_SPEC.md) — the core engine: wire/authoring Pydantic models, the
+  IR/AST compiler (capture → normalize → validate → emit), and the deterministic plan
+  validator (rules R1–R10, C1–C3, node rules W1–W4 / H1–H6).
+- [`OPUS_SPEC.md`](OPUS_SPEC.md) — the scaffolding: node classes, the layered REST client,
+  the deployer/CLI, and the Pytest suite structure.
+
+**Every change to architectural logic MUST conform strictly to these specs.** If a task
+requires behavior that contradicts a spec, stop and update the spec first (a reviewable
+change) — do not diverge in code. If the two specs disagree, `FABLE_SPEC.md` governs the
+core engine and `OPUS_SPEC.md` governs everything that depends on it. When in doubt, cite the
+governing section (e.g. "FABLE §3.4 C1") in the PR description and the code comment.
+
+---
+
+## Toolchain & Standards (enforced)
+
+| Concern | Requirement |
+|---|---|
+| **Language** | Python **3.12+**. This is the floor; do not use syntax or stdlib that predates 3.12, and do not lower it. |
+| **Dependency & packaging** | **Poetry** only. All deps, scripts, and tool config live in `pyproject.toml`. Do not add `requirements.txt`, `setup.py`, or `pip install` steps. |
+| **Data modeling** | **Pydantic v2** exclusively. No v1 APIs, no `pydantic.v1` shim. |
+| **Testing** | **Pytest**. No `unittest`, no `nose`. Property tests use Hypothesis (per OPUS §3.3). |
+| **Typing** | **`mypy --strict`** must pass with zero errors. Fully annotate every signature; no implicit `Any`, no untyped `def`. `ruff` also gates the build. |
+
+> **Version note.** OPUS §3.7's CI matrix is Python 3.12 / 3.13. **3.12 is the strict
+> floor** — never reintroduce 3.10/3.11 support or compatibility shims for them.
+
+---
+
+## Pydantic v2 rules (non-negotiable)
+
+The wire/authoring split (FABLE §1) is the single most important decision in the engine.
+Preserve it.
+
+- **Wire models** (`n8n_iac.core.wire`) are serialization-exact and derive from a shared
+  `StrictBase`:
+
+  ```python
+  class StrictBase(BaseModel):
+      model_config = ConfigDict(
+          extra="forbid",            # unknown keys on the wire are a bug
+          populate_by_name=True,     # snake_case in Python, camelCase on the wire
+          alias_generator=to_lower_camel,
+          validate_assignment=True,
+          frozen=True,               # immutable post-construction
+          ser_json_bytes="base64",
+      )
+  ```
+
+  `extra="forbid"` applies to the **envelope and node metadata only**. Node `parameters`
+  stay `dict[str, Any]` at the wire layer (FABLE §1.1) — n8n's parameter space is open.
+  Parameter strictness lives in the **node schema layer** (FABLE §1.4), never on the wire model.
+
+- **Authoring models** (`n8n_iac.core.dsl`) are the Python-facing classes. They are **never
+  serialized directly** — the compiler lowers them to wire models.
+
+- Node classes (OPUS §1.1) **validate nothing themselves**: `**params` is stored raw and
+  validated by the compiler against `PARAMS_MODEL`. One validation site, one diagnostic format.
+
+- Pydantic `ValidationError` is **never** raised to the user. The boundary layer converts it
+  into `SchemaViolation` diagnostics (FABLE §1.5).
+
+- Version-conditional and discriminated shapes use Pydantic **discriminated unions**, not
+  branching code (FABLE §1.4: `Webhook` `multipleMethods`, HTTP Request `authentication`).
+
+---
+
+## Determinism (a tested property, not an aspiration)
+
+Byte-identical JSON on every machine and every run is a hard requirement (FABLE §2.2, §3.3):
+
+- Never iterate a `dict`/`set` for anything that reaches output; use the canonical order from
+  compiler pass b6.
+- Node IDs and `webhookId` are `uuid5`-derived from a required `Workflow.uid` — **never**
+  `uuid4`, never random.
+- Diagnostics sort by `(severity, rule_id, node_name, port, index)`; cycles report in
+  lexicographically-minimal rotation.
+- `PYTHONHASHSEED` independence is tested (OPUS §3.2 hash-seed matrix). Do not weaken it.
+
+---
+
+## Testing & coverage
+
+- Suite layout is fixed by OPUS §3.1 (`unit/`, `integration/`, `e2e/`, `property/`, `golden/`,
+  `contract/`). Add tests to the matching directory.
+- Coverage target is **100% line and branch** on `n8n_iac/` (`--cov-fail-under=100
+  --cov-branch`, OPUS §3.6). Every `raise` path and both branches of every discriminated
+  union / version gate need a test. No blanket `# pragma: no cover`.
+- E2E tests (`@pytest.mark.e2e`) need a real n8n and are excluded by default.
+
+---
+
+## Common commands
+
+```bash
+poetry install                      # set up the environment
+poetry run pytest                   # full suite (e2e excluded by default)
+poetry run pytest tests/unit        # fast unit tests
+poetry run pytest -m e2e            # opt-in live tests (needs Docker + n8n)
+poetry run pytest --update-golden   # regenerate golden files (review the diff!)
+poetry run mypy --strict n8n_iac    # strict type check — must be clean
+poetry run ruff check n8n_iac       # lint gate
+```
+
+---
+
+## Working here
+
+- Match the surrounding code's idiom, naming, and comment density.
+- Do not add API transport logic to the core engine, or planning logic to the transport layer
+  — the layering in OPUS §2.1 is strictly downward.
+- When you touch a rule (R*, C*, W*, H*) or a lowering function, update the corresponding
+  golden fixture and the targeted mutation test (OPUS §3.3–§3.4).
@@ -0,0 +1,93 @@
+# Contributing to n8n-iac
+
+Thanks for considering a contribution. This project has unusually strict gates for its size —
+they exist because the whole value proposition is *trustworthy* output, and they are cheap to
+keep green if you run them as you go.
+
+## The specs are the source of truth
+
+Architecture is defined in two documents, and code implements them rather than reinterpreting
+them:
+
+- [`FABLE_SPEC.md`](FABLE_SPEC.md) — wire/authoring models, the compiler pipeline, and the
+  validator rules (R1–R10, C1–C4, W1–W4, H1–H6, S1–S3).
+- [`OPUS_SPEC.md`](OPUS_SPEC.md) — node classes, the REST client, the deployer/CLI, and the test
+  suite layout.
+
+**If a change requires behavior that contradicts a spec, update the spec first**, in its own
+commit, so the decision is reviewable on its own terms. Don't diverge silently in code. Where the
+two disagree, `FABLE_SPEC.md` governs the core engine. Cite the governing section in your PR
+description and in the code comment (e.g. "FABLE §3.4 R5").
+
+## The four gates
+
+All four must pass. CI runs them on Python 3.12 and 3.13 across Linux, macOS, and Windows.
+
+```bash
+poetry install
+poetry run pytest --cov --cov-branch    # 100% line AND branch, no exceptions
+poetry run mypy --strict n8n_iac        # zero errors, fully annotated
+poetry run ruff check n8n_iac tests
+```
+
+No Poetry on your machine? A plain venv works — `pip install -e .` plus the dev dependencies, or
+just set `PYTHONPATH=.`.
+
+### On the coverage gate
+
+100% line *and* branch is the target, and `--cov-fail-under=100` enforces it. Both sides of every
+discriminated union and every version gate need a test, and so does every `raise` path.
+
+Blanket `# pragma: no cover` is not accepted. An individual pragma is, when the line is genuinely
+unreachable — but it must carry its justification inline and it will be scrutinized in review.
+There is currently exactly one in the codebase.
+
+### On typing
+
+`mypy --strict` means no implicit `Any` and no untyped `def`. Two house rules beyond that:
+
+- Prefer an explicit `raise` over `assert` for narrowing. `assert` produces a branch that
+  coverage can never satisfy, which is why the gate keeps catching it.
+- Pydantic `ValidationError` must never escape to the user. Convert it to a `SchemaViolation`
+  diagnostic at the boundary (FABLE §1.5) so there is one diagnostic format.
+
+## Determinism is a tested property
+
+Byte-identical JSON on every machine, every run, under any `PYTHONHASHSEED`. When touching
+anything that reaches output:
+
+- Never iterate a `dict` or `set` for ordering — use the canonical order from compiler pass b6.
+- Node IDs and `webhookId` are `uuid5`-derived from `Workflow.uid`. Never `uuid4`, never random.
+- Diagnostics sort by `(severity, rule_id, node_name, port, index)`.
+
+## Where tests go
+
+The layout is fixed by OPUS §3.1 — put your test in the matching directory:
+
+| Directory            | For                                                        |
+| -------------------- | ---------------------------------------------------------- |
+| `tests/unit/`        | Single functions, lowering, individual rules                |
+| `tests/integration/` | Deployer against the in-process `FakeN8n`                   |
+| `tests/property/`    | Hypothesis invariants over generated DAGs                   |
+| `tests/golden/`      | Snapshot fixtures (`pytest --update-golden` to regenerate)  |
+| `tests/e2e/`         | `@pytest.mark.e2e` — needs a real n8n, excluded by default  |
+
+When you change a rule (R\*, C\*, W\*, H\*) or a lowering function, update the corresponding golden
+fixture **and** the targeted mutation test. Review the golden diff by hand — `--update-golden`
+will happily bless a regression.
+
+## Especially wanted
+
+- **Live-instance testing.** The e2e suite is the biggest gap in the project; everything today
+  runs against a fake. Docker-compose fixtures and `@pytest.mark.e2e` coverage are the single
+  most valuable contribution right now.
+- **Node schemas.** 16 types are modeled out of hundreds. Adding one is self-contained: a
+  `PARAMS_MODEL`, a registry entry, and tests.
+- **Bug reports with a minimal reproducing workflow.** A 10-line `Workflow(...)` that
+  misbehaves is worth more than a long description.
+
+## Pull requests
+
+Keep the diff focused, explain *why* in the description, and cite the spec section for anything
+architectural. If you're planning something large, open an issue first so we can agree on the
+approach before you write it.