shard-wiki/CLAUDE.md

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.

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.