docs(windows): WSL troubleshooting guide; point UNSUPPORTED_PLATFORM at it (#152)

docs(windows): WSL troubleshooting guide; point UNSUPPORTED_PLATFORM at it

Author: AgriciDaniel

CHANGELOG.md

@@ -5,6 +5,21 @@ Notable changes to claude-obsidian are recorded here using
 [Semantic Versioning](https://semver.org/). Git history retains the detailed
 implementation record for older releases.
 
+## [Unreleased]
+
+### Added
+
+- `docs/windows-wsl.md`: platform support matrix and WSL troubleshooting for
+  native Windows users, covering the virtualization-conflict hang class
+  (`wsl --status` hanging after install), approval-hash environment binding,
+  and filesystem identity requirements. Linked from the README, install
+  guide, compound vault guide, and the wiki skill's transaction reference.
+
+### Changed
+
+- The `UNSUPPORTED_PLATFORM` refusal message now points to
+  `docs/windows-wsl.md` for users whose WSL setup is itself misbehaving.
+
 ## [2.1.0] - 2026-07-31
 
 Native Windows compatibility.

README.md

@@ -20,7 +20,8 @@
   <a href="#from-source-to-living-knowledge">See the workflow</a> ·
   <a href="#quick-start">Quick start</a> ·
   <a href="#15-skills-one-system">Explore the skills</a> ·
-  <a href="docs/install-guide.md">Installation guide</a>
+  <a href="docs/install-guide.md">Installation guide</a> ·
+  <a href="docs/windows-wsl.md">Windows &amp; WSL</a>
 </p>
 
 claude-obsidian is a local-first knowledge system for Claude Code and compatible
@@ -349,11 +350,12 @@ CI exercises Linux and macOS, plus a native-Windows smoke job for the portable
 surface. On native Windows (including Git Bash), read-only inspection and
 dry-run commands work; vault writes require WSL and fail closed with an
 `UNSUPPORTED_PLATFORM` error otherwise. Approval hashes bind to the reviewing
-environment's filesystem identity, so run the dry-run review inside WSL when
-the apply will happen there — a natively produced `approved_plan_sha256`
-cannot be replayed from WSL. The bash setup scripts and shell test suites
-remain POSIX-only. Optional tools such as Obsidian CLI, Ollama, and defuddle
-are capability-detected and affect only their dependent workflow.
+environment, so review inside WSL when the apply will happen there. Platform
+details, the support matrix, and WSL troubleshooting (including hangs from
+virtualization conflicts) live in the
+[Windows and WSL guide](docs/windows-wsl.md). The bash setup scripts and shell
+test suites remain POSIX-only. Optional tools such as Obsidian CLI, Ollama,
+and defuddle are capability-detected and affect only their dependent workflow.
 
 ## Development and release
 

claude_obsidian/transaction.py

@@ -1388,7 +1388,8 @@ def _require_lock_dirfd_support() -> None:
 _UNSUPPORTED_PLATFORM_MESSAGE = (
     "vault writes require directory-descriptor confinement (WSL/Linux or "
     "supported macOS); on native Windows run this command inside WSL — "
-    "read-only inspection and dry-runs work natively"
+    "read-only inspection and dry-runs work natively; if WSL itself "
+    "misbehaves, see docs/windows-wsl.md"
 )
 
 

docs/compound-vault-guide.md

@@ -76,7 +76,8 @@ require WSL/Linux or supported macOS; native Windows and Git Bash are not
 supported mutation hosts and are refused with `UNSUPPORTED_PLATFORM` before
 any side effect. Read-only inspection and dry-runs run natively on Windows
 using point-in-time lstat validation (symlink and junction rejection) instead
-of descriptor pinning.
+of descriptor pinning. Platform specifics and WSL troubleshooting live in the
+[Windows and WSL guide](windows-wsl.md).
 
 Raw source bytes can be supplied through hash-checked binary `content_file`
 writes, but their destination mode is create-only. Address allocation, page

docs/install-guide.md

@@ -15,6 +15,8 @@ for development, but a normal user vault should be a separate directory.
 - Obsidian when you want its visual editor
 - Bash for installer and optional legacy-extension scripts
 - Git only for source development, release builds, or explicit checkpoints
+- On Windows: WSL for vault writes; native Windows supports read-only
+  inspection and dry-runs — see the [Windows and WSL guide](windows-wsl.md)
 
 ## Claude Code marketplace
 
@@ -258,5 +260,8 @@ User notes, sources, ledgers, and Obsidian settings remain untouched.
 | Transaction conflict / exit 75 | Another operation is active or a target changed; reread, rebuild, and inspect a new bundle. |
 | Obsidian CLI is unavailable | Use filesystem reads; start/update Obsidian before retrying CLI transport. |
 | Capture adapter is not implemented | Inspect `capture adapters`; configure a separate runner only with explicit consent. |
+| Writes refused with `UNSUPPORTED_PLATFORM` on Windows | Vault mutation requires WSL; see the [Windows and WSL guide](windows-wsl.md). |
+| WSL installed but `wsl --status` hangs | Virtualization conflict class; work through the checklist in the [Windows and WSL guide](windows-wsl.md#wsl-troubleshooting). |
+| Native dry-run approval fails in WSL with `PLAN_CHANGED` | Approval hashes bind the reviewing environment; redo the dry-run inside WSL ([details](windows-wsl.md#wsl-troubleshooting)). |
 
 Run `make test` in the product repository when developing or packaging changes.

docs/windows-wsl.md

@@ -0,0 +1,71 @@
+# Windows and WSL guide
+
+claude-obsidian supports native Windows as a read-only platform and WSL as the
+full-capability platform. This guide covers what works where, why the boundary
+exists, and how to unstick WSL when it misbehaves.
+
+## Platform support
+
+| Capability | WSL / Linux / macOS | Native Windows (incl. Git Bash) |
+|---|---|---|
+| Inspection, dry-run previews, retrieval | Yes | Yes |
+| Vault writes (`transaction apply`, `init`, `adopt`, `migrate`, `capture apply`, `mode set`) | Yes | No — refused with `UNSUPPORTED_PLATFORM` |
+| Capture queue commands (including read-only `capture queue list`) | Yes | No — currently refused; tracked in [#151](https://github.com/AgriciDaniel/claude-obsidian/issues/151) |
+| Git checkpoints (`checkpoint`) | Linux and macOS only | No |
+| Bash setup scripts and shell test suites | Yes | No (POSIX-only) |
+
+Vaults must live on a filesystem with stable file identity: NTFS is fine, but
+FAT/exFAT volumes (typical USB sticks) and some network shares are refused with
+`UNSAFE_VAULT_IDENTITY` — move the vault to NTFS or work inside WSL.
+
+## Why writes require WSL
+
+Mutation safety is bound to POSIX directory descriptors: the vault root and
+every runtime directory stay pinned for the whole write, so a concurrently
+swapped symlink or replaced folder fails closed instead of redirecting the
+write (see the [compound vault guide](compound-vault-guide.md)). Native Windows
+cannot provide those primitives, so writes are refused up front rather than
+silently running with weaker guarantees.
+
+A degraded native-Windows write mode — default-off, behind an explicit
+reduced-guarantees flag — is under consideration in
+[#151](https://github.com/AgriciDaniel/claude-obsidian/issues/151). If WSL is a
+blocker for you, that issue is the place to weigh in.
+
+## WSL troubleshooting
+
+WSL being "installed" does not always mean WSL is working. Symptoms and checks,
+roughly in the order worth trying:
+
+| Symptom | Check |
+|---|---|
+| `wsl --install` completed but `wsl --status` or `wsl -l -v` hangs indefinitely | This is usually a virtualization conflict, not a claude-obsidian issue. Work through the virtualization checklist below. |
+| `wsl` reports a kernel or version error | Run `wsl --update`, then `wsl --shutdown`, then retry. |
+| WSL worked before and stopped after an update or new security software | Check whether memory integrity / Virtualization-Based Security settings changed; VBS and other hypervisors can conflict with the Hyper-V platform WSL 2 depends on. |
+| Approval hash from a native dry-run fails inside WSL with `PLAN_CHANGED` | By design: the approval hash binds the reviewing environment's filesystem identity. Run the dry-run review inside WSL when the apply will happen there; a natively produced `approved_plan_sha256` cannot be replayed from WSL. |
+| Writes fail with `UNSAFE_VAULT_IDENTITY` mentioning stable file identity | The vault sits on FAT/exFAT or an unsupported network share. Move it to NTFS, or keep it inside the WSL filesystem. |
+
+Virtualization checklist for the hang class:
+
+1. Confirm virtualization is enabled in BIOS/UEFI (often "Intel VT-x",
+   "AMD-V", or "SVM").
+2. Confirm the Windows features "Virtual Machine Platform" and "Windows
+   Subsystem for Linux" are both enabled, and reboot after enabling them —
+   the reboot is not optional.
+3. Run `wsl --update` from an elevated prompt, then `wsl --shutdown`, then
+   retry `wsl --status`.
+4. Check that the Hyper-V "Host Compute Service" (`vmcompute`) is running;
+   restart it if stopped.
+5. If hangs persist, look for conflicts between Virtualization-Based Security
+   (memory integrity) or third-party hypervisors and the Hyper-V platform —
+   this conflict class is hardware- and configuration-specific and can survive
+   reboots until the conflicting feature is reconfigured.
+
+## Working across the boundary
+
+The supported native-Windows workflow is: inspect and review natively, mutate
+inside WSL. Because approval hashes bind to the environment that produced
+them, do the reviewed dry-run in the same environment that will run the apply.
+Keeping the vault inside the WSL filesystem (rather than on a mounted Windows
+drive) avoids both the identity caveats above and cross-boundary performance
+overhead.

skills/wiki/references/operation-transactions.md

@@ -98,7 +98,7 @@ I/O, so replacing a public root, metadata, transaction, operation, or backup
 entry cannot redirect reads, writes, rollback, or cleanup outside the selected
 vault. This confinement requires POSIX directory descriptors and
 `fcntl.flock`; Windows users must run the skill under WSL rather than native
-Windows or Git Bash.
+Windows or Git Bash (setup and troubleshooting: `docs/windows-wsl.md`).
 
 ## Required coupled writes
 

tests/test_windows_compat.py

@@ -314,6 +314,7 @@ def test_apply_refused_before_any_side_effect() -> None:
             "UNSUPPORTED_PLATFORM", apply_bundle, vault, operation
         )
         assert "WSL" in str(exc)
+        assert "docs/windows-wsl.md" in str(exc), "refusal must point at the guide"
         assert not (vault / ".vault-meta").exists(), "refusal must be side-effect free"
         assert not (vault / "wiki" / "A.md").exists()