diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..688e2db
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository status
+
+This is an **early-stage Python repository**. The package scaffold (`src/shard_wiki/`, `tests/`, `pyproject.toml`) exists with only smoke tests — the domain model is not yet implemented. Read `INTENT.md` in full before designing anything; it is the authoritative specification of what this repository is and is not. You are still establishing conventions, so keep new code consistent with the domain vocabulary below.
+
+## What this project is
+
+`shard-wiki` is a **Git-based Markdown wiki orchestrator and federation layer**, not a wiki engine. It lets multiple heterogeneous wiki-shaped page stores (**shards**) attach to a shared root entity and be presented as a **union of pages**, while preserving each shard's separate storage, provenance, capabilities, and history.
+
+The core job is orchestration across backends — Git repos, repo subdirectories (`wiki/`), Gitea wikis, local folders, Obsidian vaults, WebDAV/Nextcloud directories, Coulomb spaces — never replacing or homogenizing them.
+
+## Core domain model (the concepts code must honor)
+
+These abstractions come from `INTENT.md` and define the architecture. New code should map onto them rather than inventing parallel vocabulary:
+
+- **Shard** — an independently meaningful page store attached to a root entity. Shards have *sovereignty*: their own backend, capabilities, limits, history, and identity model. Not all shards are Git-native.
+- **Root entity / information space** — the joined space that shards attach to. Each information space should have a **Git-addressable coordination layer** (history, patches, review, backup, reconciliation) even when individual shards are not Git-native.
+- **Shard adapter contract** — the versioned interface a backend implements to participate. Adapters are **capability-aware**: the core must model explicitly which operations a shard supports (read, write, diff, merge, lock, version, publish, accept patches) rather than assuming uniformity.
+- **Wiki page model** — a stable, versioned, Markdown-first but backend-neutral representation of pages, paths, links, metadata, revisions.
+- **Projection** — a lazy, cache-like local view of remote/external shard content. Prefer lazy projection over eager copying.
+- **Overlay** — a non-destructive local edit against a remote, read-only, or capability-limited shard, representable as drafts/patches/commits/merge requests *before* destructive application ("overlay before mutation").
+- **Coordination journal** — the Git-backed record of change flows for an information space.
+- **Shard modes** — read-only, write-through, mirrored, projected, cached, canonical.
+
+## Design constraints to enforce in code
+
+These are hard boundaries from `INTENT.md`; treat violations as design bugs:
+
+- **Mechanism over policy.** Provide primitives for federation, sync, overlays, patching, conflict detection, projection, reconciliation. Do *not* hard-code one editorial/sync/conflict/canonical-source policy — keep those configurable.
+- **Union without erasure.** Always preserve provenance: which shard a page came from, its freshness, whether it is cached, whether it has overlays, whether it diverges from an equivalent page elsewhere. Never hide authorship, conflicts, freshness, or backend limitations.
+- **No silent remote mutation.** Do not mutate remote systems without explicit adapter support and user intent.
+- **Graceful degradation.** Limited backends must still be usable as read-only/cache/projection/backup/patch targets.
+- **Not a file-sync daemon.** Synchronization is wiki-page-semantic, not generic file mirroring.
+
+`INTENT.md` has a "Stability Note": changes that redefine what a shard is, Git's role, how root entities are modeled, or whether this is an orchestrator vs. an engine are **architectural changes** and should be rare and deliberate.
+
+## Build, test, run
+
+Python with a `src/` layout, built via hatchling, tested with pytest. Tests run against the source tree directly (`pythonpath = ["src"]` in `pyproject.toml`), so no install/editable step is required to run them.
+
+```bash
+pip install -e ".[dev]"   # one-time: install dev tooling (pytest, pytest-cov, ruff)
+pytest                    # run the full test suite
+pytest tests/test_package.py::test_version_is_exposed  # run a single test
+pytest --cov              # run with coverage
+ruff check                # lint
+ruff format               # format
+```
+
+Note: the system `pytest` is 7.4.x; `minversion` in `pyproject.toml` is pinned to `7.0` to match. Bump it if a newer pytest is installed into the dev environment.
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..01b51b1
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shard-wiki"
+version = "0.0.0"
+description = "Git-based Markdown wiki orchestrator and federation layer"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT-0"
+authors = [{ name = "Bernd Worsch", email = "bernd.worsch@gmail.com" }]
+keywords = ["wiki", "markdown", "git", "federation", "orchestration"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/tegwick/shard-wiki"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shard_wiki"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"
+pythonpath = ["src"]
+
+[tool.coverage.run]
+branch = true
+source = ["shard_wiki"]
+
+[tool.ruff]
+src = ["src", "tests"]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
diff --git a/src/shard_wiki/__init__.py b/src/shard_wiki/__init__.py
new file mode 100644
index 0000000..2f89c86
--- /dev/null
+++ b/src/shard_wiki/__init__.py
@@ -0,0 +1,10 @@
+"""shard-wiki — Git-based Markdown wiki orchestrator and federation layer.
+
+See INTENT.md for the authoritative specification of scope and boundaries.
+This package orchestrates wiki-shaped content across heterogeneous *shards*;
+it is not itself a wiki engine.
+"""
+
+__version__ = "0.0.0"
+
+__all__ = ["__version__"]
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_package.py b/tests/test_package.py
new file mode 100644
index 0000000..ee64bd4
--- /dev/null
+++ b/tests/test_package.py
@@ -0,0 +1,17 @@
+"""Smoke tests for the package scaffold.
+
+These exist to prove the test harness and import path are wired correctly.
+Replace/extend them as the domain model (shards, adapters, projections,
+overlays — see INTENT.md) takes shape.
+"""
+
+import shard_wiki
+
+
+def test_package_imports():
+    assert shard_wiki is not None
+
+
+def test_version_is_exposed():
+    assert isinstance(shard_wiki.__version__, str)
+    assert shard_wiki.__version__