Notable changes to claude-obsidian are recorded here using Keep a Changelog categories and Semantic Versioning. Git history retains the detailed implementation record for older releases.
Legacy migration safety and clearer Windows and WSL support guidance.
docs/windows-wsl.md: platform support matrix and WSL troubleshooting for native Windows users, covering Microsoft's diagnostic flow for unconfirmedwsl --statushangs, approval-hash environment binding, and filesystem identity requirements. Linked from the README, install guide, compound vault guide, and the wiki skill's transaction reference.
- The
UNSUPPORTED_PLATFORMrefusal message now points todocs/windows-wsl.mdfor users whose WSL setup is itself misbehaving. - Windows and WSL troubleshooting now routes unconfirmed hangs through Microsoft's diagnostic flow without asserting an unsupported cause.
- Legacy migration and adoption no longer fail when a manifest source key is a valid batch label rather than a file. Unresolved labels are preserved as unreviewed manual sources without inventing payload mappings or hashes. Apply now rejects a reviewed migration if a legacy locator's file state changes or becomes unsafe before the transaction writes.
- Migration and adoption keep read-only source observations separate from the 1,024-write recovery limit, preserving valid legacy manifests with larger source sets.
- Git-backed release and checkpoint fixtures now ignore machine-wide hooks and commit-signing settings, keeping the hermetic suite offline and deterministic.
Native Windows compatibility.
- Native Windows no longer crashes with
AttributeError: os.O_DIRECTORYon every vault command. Read-only inspection and dry-runs (transaction inspect,migrate/init/adopt/capturepreviews) now work natively with real equivalent safety checks: path-based casefold-alias auditing, lstat-based vault identity, and symlink/junction rejection. - File reads in the transaction core now force binary mode (
O_BINARY), so CRLF content is hashed byte-exactly on Windows instead of producing falseCONTENT_HASH_MISMATCH/EXPECTED_HASH_MISMATCHfailures. - CLI output is always UTF-8, fixing
UnicodeEncodeErrorcrashes when redirecting output containing non-ASCII titles on Windows (cp1252 consoles). - Retrieval no longer returns zero results for vaults with CRLF line endings:
the chunker, index, and retriever now hash page bodies byte-identically
(previously
read_textnewline normalization made every chunk look stale). - Under a held mutation lock, a vault whose on-disk name differs only by case from the spelling used on the command line is no longer misreported as its own portable alias on case-insensitive filesystems (APFS; the lock layer never runs on native Windows); the descriptor-pinned vault object is recognized as itself. Inspect-time auditing keeps the stricter shipped behavior, since an absent init root on a case-insensitive volume cannot distinguish itself from an alien sibling.
- Vault mutation on hosts without directory-descriptor confinement (native
Windows) is refused before any side effect with a new
UNSUPPORTED_PLATFORMvalidation error (exit 2, previously a genericLOCK_FAILEDexit 1 or a traceback), andinit --applyno longer creates an abandoned empty vault directory on refused platforms. - New transaction write destinations are validated against
portable-filesystem rules on every platform: Windows-reserved device names
(
CON,NUL, ...),:<>|?*"characters, and trailing dots/spaces are rejected withUNPORTABLE_WRITE_PATHso an approved plan means the same thing everywhere. Reads, retrieval indexing, and journal recovery of pre-existing files with such names are intentionally unaffected. - Degraded-mode path walks now reject Windows directory junctions and mount points in addition to symlinks.
- File permission bits feeding plan hashes are normalized to
0o644on Windows, keeping inspect output deterministic. - Added a
.gitattributesthat disables line-ending translation so checkouts hash identically on every platform. - CI gained a
windows-smokejob exercising the portable Python surface and the new Windows compatibility suite onwindows-latest. - Replaced the animated README hero with the selected static PNG cover while preserving the warm orbital style.
Reliability and evidence refoundation.
- Standard-library
claude_obsidiancore with fail-closed vault selection, recoverable operation transactions, crash recovery, exact changed-path manifests, and explicit Git checkpoints. - Deterministic Obsidian linting, product and capability contracts, portable package validation, source and claim ledgers, and additive legacy migration.
- Dry-run-first
init,adopt, methodology configuration, source capture, extension setup, and public artifact build and audit commands. - Offline-first content-addressed capture and durable queues. Image, PDF, and EPUB support is metadata-only unless a separately configured adapter is explicitly approved.
- Reproducible clean-Git ZIP builder with manifests, checksums, deterministic executable modes, and defenses for secrets, private paths, live-vault state, symlinks, traversal, collisions, unreviewed binaries, and hostile archives.
- Artifact-only marketplace generation: development source keeps a reviewed
catalog template under
config/; release build injects it only into the distribution-clean root and verifies that the promoted tree can rebuild. - Deterministic templates and sample vault, Linux and macOS CI, root-isolation tests, concurrency and failure-injection coverage, and automatic test discovery.
- Adversarial regression coverage for symlink and parent-swap escapes, stale approvals, signed credential URLs, provenance violations, staged Git state, checkpoint interruption, and transaction finalization windows.
- Rebuilt the README around the product promise, compounding loop, real vault examples, concise onboarding, trust architecture, and honest capability boundaries.
- Adopted the warm orbital cover system, added the selected metadata-stripped static PNG cover, preserved the Obsidian screenshots, and aligned the self-contained SVG architecture diagrams to the new style.
- All 15 skills now use canonical two-field Agent Skills frontmatter and one host-neutral operation contract.
- Parallel ingestion and research workers are draft-only. One orchestrator inspects and applies the complete knowledge operation.
- Query and lint are read-only. Persistence and repairs are separate reviewed operations.
- Claude hooks are bounded SessionStart and Stop adapters. Stop reports recovery
state; SessionStart context injection requires the explicit
CLAUDE_OBSIDIAN_SESSION_CONTEXT=1opt-in. Neither mutates knowledge or Git. - Setup and installation helpers default to previews, use selected user vaults, avoid plugin-cache state, and preserve existing configuration.
- Portable installation creates directly discoverable per-skill links at each host's current skill root, and executable skills resolve product helpers by absolute installed paths rather than the user-vault working directory.
- Retrieval now removes stale chunks, invalidates derived indexes, deduplicates before top-K, confines paths, uses task-specific Nomic prefixes, and restores the complete BM25 result when reranking cannot be trusted. Query size and result counts are bounded; invalid limits and oversized queries fail with nonzero, actionable usage errors.
- CJK retrieval now normalizes Unicode input and indexes bounded character n-grams so Japanese, Chinese, Korean, Bopomofo, and mixed-width queries can overlap longer documents; legacy derived indexes fail closed with rebuild guidance.
- Optional semantic reranking defaults to the multilingual Nomic v2 MoE model, uses Ollama's current single-input embed API, supports explicit model selection with exact tag semantics, and retains deterministic BM25 order when the selected local model is unavailable.
- Public release scanning rejects recognizable personal email addresses while retaining only reserved example domains and GitHub-generated noreply identities for fixtures and provenance; SSH clone locators and numeric package-version specifiers are not misclassified as email addresses.
- Product source, user vaults, deterministic templates, and public artifacts are explicit separate roles.
- Distributable setup references now follow the same transaction, privacy, plugin-review, TLS, and evidence boundaries as the skills.
- Dry-run/apply workflows are bound to exact canonical, vault-specific plan hashes. Transaction targets use no-follow vault-relative writes and unlinks, reserve product/runtime namespaces, and enforce declared workflow scopes; provenance contracts are enforced during inspect, apply, lint, and checkpoint.
- Explicit checkpoints now construct and verify Git objects through a temporary index, update refs by compare-and-swap, and recover from a durable pending record without consuming unrelated staged or intent-to-add state. Content and executable modes must both match the transaction result.
- Capability readiness now distinguishes configured workflows from genuine behavioral verification; schema/self-checks cannot promote a capability.
- Provenance identities now collapse RFC-equivalent IPv6, IDN, Unicode/IRI, default-port, dot-segment, and percent-encoding URL spellings before source independence is counted; malformed/non-scalar forms fail closed.
- Zettelkasten routing now combines its UTC microsecond prefix with a UUIDv4 nonce, preventing rapid or concurrent preview collisions without allocator writes. Legacy format metadata is normalized through reviewed mode changes, overlong UTF-8 components are hash-suffixed within the 255-byte portability floor, and existing timestamp-only filenames remain valid.
- Duplicate command mirrors and generic PostToolUse or PostCompact behavior.
- Direct shared writes, automatic Git commits, and per-file locks from the supported mutation path.
- Unsupported comparative, performance, and capability claims from current product documentation.
- Root contributor-vault Obsidian snippets from the public artifact; the project-owned deterministic template snippet remains.
- Existing vaults remain readable. Migration is additive, idempotent, and preserves the legacy raw manifest byte-for-byte.
scripts/wiki-lock.shremains a deprecated v1 compatibility helper only.- Product tools never publish, push, tag, or mutate public collaboration state without owner approval.
- Added bounded local prompt-cache statistics to explicitly approved contextual-prefix API calls.
- Hardened explicit path handling and expanded hermetic contextual-prefix tests.
- Hardened legacy lock path confinement, transport probes, cache warnings, and remote Ollama consent.
- Added operator-facing single-tenant threat-model documentation.
- Added the 10-stage OBSERVE, OBSERVE, LISTEN, THINK, CONNECT, CONNECT, FEEL, ACCEPT, CREATE, GROW reasoning skill.
- Added repository contribution, security, issue, pull-request, and CI foundations.
- Preserved manual transport overrides and hardened mode routing, input sanitization, and local vault selection.
- Expanded verifier and retrieval tests.
- Added optional Generic, LYT, PARA, and Zettelkasten methodology modes.
- Added deterministic path routing and non-destructive mode configuration.
- Added Unicode-aware BM25 tokenization and retrieval failure hardening.
- Improved cache locking, progress reporting, and invalid-input diagnostics.
- Made contextual-prefix egress explicit and added a read-only verifier role.
- Hardened transport JSON handling and legacy retrieval failure recovery.
- Added optional contextual retrieval, BM25, local reranking, transport detection, and a legacy multi-writer compatibility layer.
- Added the
wiki-cliandwiki-retrieveskills.
- Added opt-in boundary-first autoresearch and its deterministic graph scorer.
- Hardened vault path confinement and aligned DragonScale rollout metadata.
- Added opt-in fold, deterministic-address, and semantic-tiling prototypes.
- Added the initial test harness and extension setup helpers.
- Earlier project history remains available in Git.