magicite 1.0.0__tar.gz

magicite-1.0.0/.dockerignore

@@ -0,0 +1,49 @@
+# Keep the build context small and hermetic.
+# The production Dockerfile only copies pyproject.toml + README.md + src/;
+# Dockerfile.dev also copies tests/. Everything else is noise, and some of
+# it (`.magicite/`, `.spectra/`, `.eidolons/`, `.mcp.json`) must never end up baked into
+# a published image.
+
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+dist/
+build/
+*.egg-info/
+
+# Registry/runtime state — never ships in the image; the container reads
+# it from a bind-mounted VOLUME at runtime instead. `.magicite/` is
+# Magicite's own; `.spectra/` is ESL/tonberry's and is equally unwelcome
+# in a published image.
+.magicite/
+.spectra/
+
+.eidolons/
+.atlas/
+.claude/
+.codex/
+.git/
+.gitignore
+.github/
+
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Never ship local secrets (or any MCP client config carrying tokens) into
+# an image.
+.env
+.env.*
+.mcp.json
+eidolons.mcp.lock

magicite-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Machine-local MCP wiring (absolute paths, restricted mode)
+.mcp.json
+eidolons.mcp.lock
+
+# Eidolons scratch state
+# .atlas/ is entirely generated scout state (symbol index, graph db, locks)
+.atlas/
+.eidolons/.context/
+.eidolons/memories/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Magicite runtime state — the graph DB is a rebuildable index (CR-2).
+# Set MAGICITE_COMMIT_DB=1 and remove these lines to track it instead.
+skill-graph.db
+skill-graph.db-wal
+skill-graph.db-shm
+
+# Ephemeral worktrees used for fail-before/pass-after proofs
+.claude/worktrees/
+
+# The three directories Config.ensure_dirs() creates at every `magicite serve`
+# boot. Machine-local runtime state, not deliverables: approvals are pending
+# proposals awaiting a local decision, and committing them would invite another
+# machine to approve a proposal it never reviewed. The engram registry itself
+# (.magicite/engrams/*.egr.md) IS tracked — it is the source of truth.
+/.magicite/approvals/
+/.magicite/runtime/
+/.magicite/archive/

magicite-1.0.0/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/). Version 1.0.0
+bounds its promise to implemented functionality; it does not claim the research
+hypothesis, scale budgets, or independent security certification are established.
+Historical entries and their original limitations remain below.
+
+## [Unreleased]
+
+## [1.0.0] — 2026-10-11
+
+- Release the existing local MCP knowledge workflow, stable dense default,
+  protected trust/lifecycle operations, and `magicite init --host claude`.
+- Align installation and setup with GitHub wheel/source packages and signed OCI;
+  production PyPI remains deferred.
+- Record the maintainer-approved functional scope and open qualification work
+  in [release notes](docs/releases/1.0.0.md).
+
+## [0.3.1] — 2026-08-18
+
+### Changed
+
+- SKILL.md import/export now preserves arbitrary Markdown bodies and host-specific
+  YAML frontmatter, recognizes colonless `Use when` / `NOT for` routing
+  markers, and fails before writing when a preserved body would be exported
+  lossily.
+
+## [0.3.0] — 2026-08-18
+
+The integrity-recovery release closes the runtime, evaluation, interface, and
+verification drifts identified by the full 0.2 audit. It retains Python as the
+single routing semantic reference; native C remains deferred until a measured
+production hotspot can justify the extra implementation and integrity risk.
+
+### Added
+
+- Resumable, fenced Dream checkpoints and crash-recovery coverage.
+- Process-level lease race and stale-writer verification.
+- Recoverable idempotency reservations spanning effects, event commit, and
+  response persistence.
+- Auditable approval decisions and resume transitions.
+- An independently authored composition corpus, superseding evaluation
+  results, executable documentation contracts, and a 1k/10k benchmark matrix.
+
+### Changed
+
+- Routing uses a versioned canonical view, separate contraindication vectors,
+  shared production/evaluation activation primitives, and bounded exact cache
+  reuse.
+- Embedding operation is offline by default and live introspection reports the
+  current lifecycle, verification, execution, and learned-state dimensions.
+- CI and release inputs are immutable; the release image is signed and
+  accompanied by SBOM and provenance attestations.
+
+## [0.3.0rc1] — 2026-08-18
+
+Integrity-recovery release candidate. The final 0.3.0 tag remains blocked on
+independent review and the acceptance gates in the governed recovery plan.
+
+### Added
+
+- Recoverable durable-write checkpoints, lease fencing, fail-closed registry
+  reconciliation, migration rollback safety, and idempotency recovery.
+- A distinct contraindication routing view, production/baseline seed parity,
+  truthful live introspection, and resumable skill-body pagination.
+- `docs/AUTHORITY.md`, archive redirects, prospective agent provenance, and
+  an explicit 0.3 release-gate record.
+- Immutable GitHub Action SHAs and digest-pinned Python/uv container inputs.
+
+### Changed
+
+- Source operation is offline by default; model acquisition is explicit.
+- The route/evaluation contract supersedes 0.2 baseline-(c) measurements that
+  used a different seed rule and omitted documented inhibition.
+- Package metadata no longer embeds the image digest produced after the
+  package itself is built; the signed release record is the digest authority.
+- Performance work uses generation-keyed index reuse and differential tests.
+  No native C implementation is included.
+
+### Append-only errata for 0.1/0.2
+
+- The frozen acceptance categories total 33 (19 event-driven, 3 state-driven,
+  5 ubiquitous, 6 unwanted-behavior), plus 9 addendum criteria; the prior
+  chronicle total of 35 was an accounting error.
+- The runtime lifecycle is `nascent → probation → consolidated → promoted →
+  archived`; `active` and `dormant` in the 0.1 prose were stale design names.
+- Declared edges use the accepted effective-strength floor; the 0.1 paragraph
+  saying they remained at zero effect is superseded.
+- The `no_tag_capture` ablation is invalid and supports no Principle 0 claim.
+  Prior evidence is preserved; corrected results must be published separately.
+
+## [0.2.0] — 2026-08-16
+
+### Changed — BREAKING (data layout)
+
+- **Magicite's project state moved from `.spectra/` to `.magicite/`.**
+  `.spectra/` belongs to ESL/tonberry, which owns `.spectra/changes/`; the two
+  tenants collided confusingly (Magicite's `.spectra/archive/` — decayed
+  engrams — sat one level from ESL's `.spectra/changes/archive/` — archived
+  change records). The ecosystem convention is one dot-directory per tool
+  (`.atlas/`, `.eidolons/`), and Magicite now follows it. `engrams/`,
+  `archive/`, `approvals/`, `runtime/`, `magicite.toml`, and `bench/` all live
+  under `.magicite/`. `.spectra/changes/` is untouched.
+
+  **Existing projects keep working without intervention.** Path resolution
+  falls back to `.spectra/` when `.magicite/` is absent *and* a real
+  `.spectra/engrams/` exists — a fresh project carrying only an ESL
+  `.spectra/changes/` tree is never dragged onto the old layout. `magicite
+  doctor` reports the fallback as a deprecation warning rather than staying
+  quiet; a silent fallback against an empty registry is the worst failure mode
+  a router has. The fallback is scheduled for removal in a future minor
+  version. Migration steps: `docs/operations.md` §15.
+
+### Added
+
+- `MAGICITE_DATA_DIR` overrides the data directory name, beating both the
+  default and the legacy fallback. Environment only — `magicite.toml` lives
+  inside the directory it would be naming.
+- `magicite doctor` reports a `layout` section (`data_dir`, `legacy`,
+  `expected`) and warns on the deprecated location.
+- A first-party engram registry for this repository itself (30 engrams,
+  `.magicite/engrams/`) plus the dogfood harness under `scripts/`. See
+  `docs/adapters/dogfooding.md`, including what dogfooding exposed: notably
+  that `triggers.negative` and `intent.not_when` have **no effect on
+  retrieval** in 0.1.0 — they are linted, fitness-scored, stored, and hashed
+  into the engram id, and consulted by nothing at query time.
+
+### Unchanged
+
+- The 16-tool MCP surface, routing behaviour, plasticity, and the trust gate.
+  This release moves files and resolves paths; it changes no decision the
+  router or the Dream worker makes. No claim in `docs/01`'s Falsification
+  Record is affected.
+
+## [0.1.0] — 2026-08-15
+
+Initial release: a local-first, plasticity-inspired skill router speaking
+MCP over stdio, distributed as a self-contained, offline-capable
+container.
+
+### Honest limits, up front
+
+This section exists because the alternative — a features list without the
+measurements attached — is exactly the failure class this release is
+built to avoid. Full detail, methodology, and caveats: `docs/01-vision-
+and-hypotheses.md`'s **Falsification Record** and "What the Evidence
+Licenses" section.
+
+- **The full pipeline does not beat plain dense embedding on Hit@1.** At
+  70 skills / 210 queries, baseline (b) (dense embedding alone) scores
+  Hit@1 0.5476; the full Magicite pipeline (baseline d: embedding + graph
+  activation + learning) scores 0.5333. The gap is 3 queries out of 210 —
+  statistically indistinguishable (prior measurement: an 18-query gap,
+  p = 0.00053) — but it is not ahead. **H-BODY-b is falsified as
+  implemented.**
+- **Authored graph structure (the design's actual central claim —
+  spreading activation over declared `needs`/`composes`/`inhibits`
+  edges, not re-derived embeddings) has zero supporting measurements and
+  two non-supporting ones.** Declared edges are written at `S_edge = 0.0`
+  until Dream potentiates them, so on any registry that has not been
+  through consolidation the activation graph contains only derived
+  `similar_to` kNN edges — re-deriving the cosine signal already scored
+  by the embedding arm — and the 11 declared `inhibits` relations in the
+  70-engram benchmark registry were measured to have never had any
+  production effect. **The design's central claim remains untested as
+  designed.**
+- **Outcome-gated plasticity degraded held-out routing 3.6× under an
+  oracle teacher** (Hit@1 0.4697 → 0.1061), the opposite of the
+  prediction. Signal noise was not the binding constraint; the
+  score-combination rule is. **H-LEARN is falsified as implemented,
+  under uniform demand.**
+- **Community-hierarchy rerank contributes nothing measurable at 70
+  skills** (ΔHit@3 = 0.0000); the log-decay-flattening claim is
+  inconclusive in both directions on the data collected so far.
+- **Zero compositional queries were run.** Plan-expansion (H-COMPOSE)
+  is untested, not merely unvalidated.
+
+These results come from a single-author benchmark (corpus, queries, and
+annotation by one agent, one embedder, uniform learning workload) — see
+`docs/01` for exactly what that bias does and does not license. The
+0.4619 → 0.5333 improvement recorded in this release is **mechanism
+repair** (a declared-edges amendment and an `inhib_gain` recalibration
+that fixed defects actively suppressing measurement), not evidence that
+the design hypothesis is correct.
+
+### Added
+
+- **16-tool MCP surface** over stdio: `register`, `sync`, `route`,
+  `load_skill_body`, `signal_use`, `signal_outcome`, `session_end`,
+  `consolidate`, `checkpoint`, `nucleate`, `sharpen`, `promote`,
+  `archive`, `flag_dead`, `introspect`, `export`.
+- **`.egr.md` — a portable, human-readable, git-diffable skill format**
+  (YAML frontmatter + Markdown body), the sole source of truth for the
+  registry.
+- **A fully rebuildable index.** `skill-graph.db` (SQLite/WAL) is a
+  derived cache: delete it and `sync()` reconstructs Tier A/B durable
+  state byte-identically from the `.egr.md` files on disk (the rebuild
+  invariant, `tests/acceptance/test_rebuild_invariant.py`).
+- **Lifecycle governance**: a draft → probation → active/dormant →
+  archived state machine, approval-gated promotion/sharpening, an
+  append-only `provenance_journal` audit trail per engram, and trust
+  metadata for authored/imported/distilled origin.
+- **Offline-hardened, self-contained container image.** The `fastembed`
+  ONNX embedding model (`BAAI/bge-small-en-v1.5`) is baked in at build
+  time; the image completes its MCP handshake and a full
+  `register()`/`route()` cycle with `--network none` and no network
+  egress at runtime (`tests/acceptance/test_docker_smoke.py`). Follows
+  the same hardened, sibling-MCP pattern this project's own `.mcp.json`
+  uses for `crystalium`/`atomos`/`atlas-aci`: non-root, capability-
+  dropped, digest-pinnable.
+- **Three-tier signal ladder** (Tier-0 passive inference, Tier-1
+  tool-mediated self-report, Tier-2 host-adapter hook verification, with
+  server-side tier assignment) so learning degrades gracefully on hosts
+  without hook support, rather than requiring one.
+- **`magicite doctor`** diagnostics: filesystem-class warnings for
+  `fcntl.flock()`-degraded mounts (NFS/CIFS), and an honest registry-size
+  report that never treats crossing a reference skill count as evidence
+  of a validated break-even.
+
+### Fixed
+
+- **`provenance_journal` entries appended during a Dream checkpoint or
+  archive were computed in memory but never persisted to the `.egr.md`
+  file.** `engram/writer.py::render_frontmatter`'s round-trip branch
+  refreshed `version`/`plasticity`/`peak_storage_strength`/`synapses` on
+  the parsed YAML carrier but never `provenance_journal` — so the
+  governance audit trail `docs/06-trust-governance-lifecycle.md` sells as
+  the mechanism for autonomous-mutation oversight silently no-opped on
+  every checkpoint write. Fixed; regression-proven
+  (`tests/acceptance/test_rebuild_invariant.py::
+  test_checkpoint_persists_provenance_journal_to_file`, fails against the
+  pre-fix code and passes after).
+
+### Known gaps (tracked, not release-blocking)
+
+- Compositional (`needs`/`yields`/`composes`) routing is implemented but
+  has zero measured evaluation coverage.
+- The declared-edges amendment and `inhib_gain` recalibration repaired
+  measurement defects; they did not validate the graph-activation design
+  hypothesis, which remains the pre-registered reversal condition to
+  watch across future releases.

magicite-1.0.0/Dockerfile

@@ -0,0 +1,143 @@
+# syntax=docker/dockerfile:1
+#
+# magicite — local-first, plasticity-inspired skill router speaking MCP
+# over stdio. Production runtime image (spec §8 "Distribution & Packaging";
+# AC-026, AC-031; Risk R4). Sibling-MCP pattern verified against this
+# project's own `.mcp.json` (crystalium/atomos/atlas-aci/tonberry): a
+# non-root, UID-pinned user; `--cap-drop ALL --security-opt
+# no-new-privileges` at `docker run` time; digest-pinnable in production.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# The fastembed ONNX model (BAAI/bge-small-en-v1.5) is baked into the image
+# at BUILD time below — the one legitimate network-touching step (`magicite
+# fetch-model`) — so the container never reaches the network at runtime.
+# MAGICITE_EMBEDDING_OFFLINE=1 is set as a hard runtime default: it is
+# threaded through to fastembed's `local_files_only` kwarg
+# (embeddings/fastembed_provider.py), so a cache miss raises immediately
+# instead of ever attempting a fetch — the guarantee AC-026's "no network
+# access" clause depends on, not just a documented convention.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# PRIVILEGE-BOUNDARY NOTE — read before deploying against a real registry.
+#
+# This image's default user is `magicite`, UID 10001 (a safe, never-root
+# default for a bare `docker run image` with no `--user` override). But
+# magicite is NOT a read-only tool the way atlas-aci is: register()/sync()/
+# Dream write real files under the mounted project's `.magicite/` tree
+# (engrams, the DB, dream.lock, approvals) — and `magicite serve` calls
+# `Config.ensure_dirs()` UNCONDITIONALLY AT EVERY BOOT (creating
+# `.magicite/{archive,approvals,runtime}` if absent), not only when a write
+# tool is later called.
+#
+# CONFIRMED EMPIRICALLY (`tests/acceptance/test_docker_smoke.py`, M7): a
+# bind mount preserves the HOST's file ownership, so a container started
+# WITHOUT overriding `--user` to your own host uid:gid runs as UID 10001
+# against a `project_root` it does not own — `ensure_dirs()` hits a bare
+# `PermissionError` and the server never even completes `initialize`. This
+# is stronger than a mere ownership-hygiene concern: **the container
+# cannot function at all** against a real, host-owned project directory
+# without the `--user` override. (If you pre-create/chown `.magicite/` to
+# UID 10001 yourself, or the mount happens to be world-writable, boot will
+# succeed but every file magicite creates is then owned by UID 10001, not
+# you — the same privilege boundary FORGE's threat model (docs/02-
+# architecture.md) assumes does NOT exist between the MCP client and the
+# MCP server, since you can no longer freely edit/delete your own
+# `.egr.md` files without `sudo chown` afterward.)
+#
+# The fix is the invocation, not the image: ALWAYS pass
+# `--user "$(id -u):$(id -g)"` (or the literal `--user 1000:1000` this
+# project's own `.mcp.json` and docs/adapters/claude-code.md use) when
+# mounting a real project directory. That overrides the image's UID 10001
+# default with your own, making the container process the SAME OS
+# principal as the host client — no boundary introduced, matching every
+# other project-file-touching sibling MCP (atomos, atlas-aci, tonberry).
+# ─────────────────────────────────────────────────────────────────────────
+#
+# Quickstart (the safe, house-pattern invocation):
+#
+#   docker run --rm -i \
+#       --user "$(id -u):$(id -g)" \
+#       --cap-drop ALL --security-opt no-new-privileges \
+#       -v "$PWD":"$PWD":z -w "$PWD" \
+#       ghcr.io/rynaro/magicite@sha256:<digest> \
+#       serve --project-root "$PWD"
+#
+# ─────────────────────────────────────────────────────────────────────────
+
+FROM python:3.12-slim@sha256:2c941e860699f878900b0edc2403613c234d4b32eda3cc9fa7036991a2a63c4a AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.23@sha256:d0a0a753ab981624b49c97abc98821c1c09f4ca69d1ef5cee69c501be3d88479 /uv /usr/local/bin/uv
+
+WORKDIR /build
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+
+# Build the wheel directly. README.md is copied because pyproject.toml's
+# `readme = "README.md"` field makes hatchling require it at build time.
+RUN uv build --wheel --out-dir /dist
+
+# Export the locked transitive deps (production, no dev extras) so the
+# runtime stage installs the exact versions captured in uv.lock, not
+# whatever pip resolves fresh against PyPI at image-build time.
+RUN uv export --frozen --no-dev --no-emit-project --format requirements-txt \
+        --output-file /dist/requirements.txt
+
+# ─────────────────────────────────────────────────────────────────────────
+
+FROM python:3.12-slim@sha256:2c941e860699f878900b0edc2403613c234d4b32eda3cc9fa7036991a2a63c4a AS runtime
+
+LABEL org.opencontainers.image.title="magicite" \
+      org.opencontainers.image.description="Local-first, plasticity-inspired skill router speaking MCP over stdio" \
+      org.opencontainers.image.licenses="Apache-2.0" \
+      org.opencontainers.image.source="https://github.com/Rynaro/magicite"
+
+# The pinned slim index currently contains a fixed-but-not-yet-refreshed
+# Debian util-linux package set (CVE-2026-53615). Apply repository security
+# upgrades in the final stage so the Trivy HIGH/CRITICAL gate validates the
+# actual runtime filesystem, then discard apt metadata from the image.
+RUN apt-get update \
+ && apt-get upgrade -y --no-install-recommends \
+ && rm -rf /var/lib/apt/lists/*
+
+# Dedicated unprivileged user. UID pinned to 10001 so volume ownership is
+# predictable across rebuilds (this is the DEFAULT, not the recommended
+# runtime `--user` — see the privilege-boundary note above).
+RUN useradd --create-home --uid 10001 magicite
+
+COPY --from=builder /dist/requirements.txt /dist/*.whl /tmp/
+# Install transitive deps from the lockfile-derived requirements.txt
+# first, then the project wheel itself with --no-deps so pip cannot
+# re-resolve and undo the lock-respecting install.
+RUN pip install --no-cache-dir -r /tmp/requirements.txt \
+ && pip install --no-cache-dir --no-deps /tmp/*.whl \
+ && rm /tmp/*.whl /tmp/requirements.txt
+
+# Bake the fastembed ONNX model at build time (spec §8, R4): the container
+# must never reach the network at runtime. Root still owns the filesystem
+# here, so fetch as root, then hand ownership to the runtime user — the
+# baked cache only needs to be READABLE by whichever uid ends up running
+# the container (UID 10001 by default, or an overriding --user), never
+# written to at runtime (MAGICITE_EMBEDDING_OFFLINE=1 below forbids it).
+ENV FASTEMBED_CACHE_PATH=/opt/magicite/models
+RUN mkdir -p "$FASTEMBED_CACHE_PATH" \
+ && magicite fetch-model \
+ && chmod -R a+rX "$FASTEMBED_CACHE_PATH"
+
+RUN mkdir -p /project && chown magicite:magicite /project
+
+USER magicite
+WORKDIR /project
+
+VOLUME ["/project"]
+
+ENV HOME=/tmp \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    MAGICITE_EMBEDDING_OFFLINE=1
+
+# MCP stdio handles SIGINT cleanly; make `docker stop` fast by mapping
+# SIGTERM → SIGINT instead of the default 10s grace-then-KILL.
+STOPSIGNAL SIGINT
+
+ENTRYPOINT ["magicite"]
+CMD ["serve", "--project-root", "/project"]

magicite-1.0.0/Dockerfile.dev

@@ -0,0 +1,59 @@
+# syntax=docker/dockerfile:1
+#
+# magicite — dev-loop image.
+#
+# Separate from the production Dockerfile so the runtime image stays
+# minimal (no pytest/ruff/mypy, no fastembed model bake needed for a dev
+# loop that runs against MAGICITE_EMBEDDING_PROVIDER=hashing, this repo's
+# own test convention). Source lives under /work so bind-mounted edits
+# round-trip without rebuilds.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# Build once, run many:
+#
+#   docker build -f Dockerfile.dev -t magicite-dev .
+#
+#   # Interactive shell with everything pre-installed
+#   docker run --rm -it -v "$PWD":/work magicite-dev
+#
+#   # One-shot commands
+#   docker run --rm -v "$PWD":/work magicite-dev uv run pytest -q
+#   docker run --rm -v "$PWD":/work magicite-dev uv run ruff check src/ tests/
+#   docker run --rm -v "$PWD":/work magicite-dev uv run mypy src/
+#
+#   # Smoke-test the CLI
+#   docker run --rm -v "$PWD":/work magicite-dev uv run magicite tools
+#
+# The bind mount overlays /work with your host checkout, so edits on the
+# host are immediately visible inside the container. The cached .venv from
+# `uv sync` in the build stage is preserved because it lives outside /work
+# (UV_PROJECT_ENVIRONMENT=/opt/venv).
+# ─────────────────────────────────────────────────────────────────────────
+
+# Digest pins match production Dockerfile / CI uv 0.11.23 so the image is
+# reproducible and supply-chain-immutable (no floating `latest` tags).
+FROM python:3.12-slim@sha256:2c941e860699f878900b0edc2403613c234d4b32eda3cc9fa7036991a2a63c4a
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.23@sha256:d0a0a753ab981624b49c97abc98821c1c09f4ca69d1ef5cee69c501be3d88479 /uv /usr/local/bin/uv
+
+# Seed a venv outside /work so the bind mount can't shadow it.
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv \
+    PATH="/opt/venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /work
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY tests ./tests
+
+# `uv sync` installs the project in editable mode; hatchling reads
+# `readme = "README.md"` from pyproject.toml, so the file must be here.
+# `leiden` (python-igraph/leidenalg) is deliberately NOT installed here —
+# it is an optional extra with real wheel-availability fragility on some
+# platforms (Risk R5); CommunityDetector's automatic label_propagation
+# fallback (AC-022) is exactly what a dev loop should exercise by default.
+# Add `--extra leiden` locally if you need to test the Leiden path.
+RUN uv sync --extra dev
+
+CMD ["bash"]