heph: dev/installed isolation — mise run dev task + install how-to

- mise-tasks/dev runs the working-tree hephd on isolated .dev/ paths (gitignored)
  so in-repo development never touches the installed daemon's data; point a dev
  nvim at it via HEPH_SOCKET/HEPH_DB.
- docs/how-to/install-heph.md: install heph/hephd from the forge (build from
  source), the lazy.nvim `dir` setup for the subdir plugin, and dev isolation.
- gitignore .dev/ and the transient .claude scheduled-task state.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -11,6 +11,9 @@ __pycache__/
 # Rust
 /target/
 
+# Dev daemon data (isolated from the installed heph; see `mise run dev`)
+/.dev/
+
 # Linter caches
 .ruff_cache/
 

docs/changelog.d/v1-prototype.feature.md

@@ -18,3 +18,4 @@ Begin the v1 prototype (Phase 1, tech-spec §11.1), built in TDD slices:
 - `heph.nvim` slice 11b (§8) — task views: `list` is enriched to return titled rows (the same shape as `next`, with the canonical-context id) so the Organizational survey needs no per-row `node.get`. The plugin gains the Tactical **`:Heph next`** and Organizational **`:Heph list`** views (`<CR>` opens a task's canonical-context doc), task **capture**, **set-attention**, **done/drop**, **skip**, and per-task **`log`** append — each resolving "the current task" from the buffer (a task node, or a context doc via its `canonical-context` backlink). A `vim.ui.select` picker (Telescope auto-upgrade when installed) backs `:Heph search`/`capture`/`attention`. Headless e2e adds the capture→next→context→checklist→done workflow and the recurring fresh-checklist workflow (completing a recurring task rolls it forward and the next occurrence presents an all-unchecked checklist).
 - `heph.nvim` slice 11c (§8) — promotion + CI: `task.promote` mints a committed task from a `- [ ]` context-item line (addressed by its 1-based index) and rewrites that line into a `[[link]]` to the new task; `:Heph promote` does this for the line under the cursor. Wiki-link resolution now excludes a task's canonical-context doc, so `[[Task Title]]` resolves to the task itself (not its identically-titled context doc). The headless e2e suite runs in CI via a Dagger function that bakes a pinned, arch-detected Neovim onto a Rust image and runs the same self-contained suite developers run natively with `mise run test-nvim`; the runner fails on a zero-spec discovery so a misconfigured path can't pass silently.
 - `heph.nvim` managed daemon — plug-and-play by default: `require("heph").setup({})` spawns and supervises a local `hephd` against the default paths when none is running, kills only the daemon it spawned on exit, and self-heals (respawns + reconnects if the daemon dies mid-session). A daemon you started yourself (a `server`/`client` architecture, or a service) is always respected — the plugin only spawns when nothing is serving the socket; with `autostart = false` it connects only and warns if unreachable. `$HEPH_SOCKET` / `$HEPH_DB` isolate a development Neovim onto a separate daemon + DB.
+- Dev/installed isolation tooling: a `mise run dev` task runs the working-tree `hephd` on isolated `.dev/` paths, and a how-to ([[install-heph]]) covers installing `heph`/`hephd` from the forge (build-from-source), the lazy.nvim plugin setup, and pointing a dev Neovim at the dev daemon via `$HEPH_SOCKET`/`$HEPH_DB` so it never touches the installed store.

docs/how-to/how-to.md

@@ -13,3 +13,7 @@ Task-oriented guides for common operations.
 ## Knowledge Base
 
 - [[agent-change-process]] — C0/C1/C2 change classification and Mikado method
+
+## heph
+
+- [[install-heph]] — Install `heph`/`hephd` from the forge, set up the Neovim plugin, and isolate in-repo development

docs/how-to/install-heph.md

@@ -0,0 +1,81 @@
+---
+title: Install heph (and isolate dev)
+modified: 2026-06-02
+tags:
+  - how-to
+---
+
+# Install heph (and isolate dev)
+
+How to install `heph`/`hephd` from the forge and run the `heph.nvim` plugin,
+**isolated** from in-repo development so the two never share data. No prebuilt
+binaries yet — everything builds from source (works on macOS/arm64,
+linux/arm64, linux/amd64).
+
+## 1. Install the binaries from the forge
+
+Build and install `heph` + `hephd` to `~/.cargo/bin` (on `PATH`) from a forge
+ref. Until v1 is tagged, install from the branch:
+
+```bash
+cargo install --locked \
+  --git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
+  --branch feature/v1-prototype \
+  heph hephd
+```
+
+Re-run with `--tag vX.Y.Z` once a release is cut. This needs forge SSH access
+(an unlocked 1Password / ssh-agent key).
+
+The **installed** daemon owns the default paths — socket
+`$XDG_RUNTIME_DIR/heph/hephd.sock`, DB `$XDG_DATA_HOME/heph/heph.db` — i.e. your
+real data.
+
+## 2. The Neovim plugin
+
+`heph.nvim` lives in a subdirectory of the monorepo, and lazy.nvim can't load a
+subdir plugin from a bare git URL (it puts the clone *root* on `runtimepath`).
+For now, point lazy at a dedicated checkout via `dir`:
+
+```bash
+git clone --branch feature/v1-prototype \
+  ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
+  ~/.local/share/heph/checkout
+```
+
+```lua
+-- lazy.nvim spec
+{
+  dir = vim.fn.expand("~/.local/share/heph/checkout/heph.nvim"),
+  config = function()
+    require("heph").setup({}) -- plug-and-play: spawns + manages its own hephd
+  end,
+}
+```
+
+`setup({})` is plug-and-play — it starts and supervises a local `hephd` against
+the default paths, so you don't need a separate service. Update the plugin by
+`git pull`ing the checkout. (A future split of `heph.nvim` into its own forge
+repo will make this a normal `{ "eblume/heph.nvim" }` spec.)
+
+## 3. Isolate development
+
+In-repo development must not touch the installed store. Run the dev daemon on
+separate paths and point a dev Neovim at it:
+
+```bash
+mise run dev   # runs the working-tree hephd on .dev/hephd.sock + .dev/heph.db
+```
+
+```bash
+# dev Neovim — the plugin reads these envs and targets the dev daemon
+HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
+```
+
+The installed plugin (no envs) talks to the installed daemon; the dev Neovim
+talks to the dev daemon. They never share a socket or DB. `.dev/` is gitignored.
+
+## Related
+
+- [[heph-nvim]] — the plugin surface and its managed-daemon lifecycle
+- [[tech-spec]] — §3.1 runtime modes; the daemon's exclusive DB lock

mise-tasks/dev

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#MISE description="Run a development hephd on isolated .dev/ paths (never touches the installed daemon's data)"
+
+# Dev/installed isolation: the installed heph owns the default XDG socket+DB
+# (your real data); this runs the dev working-tree daemon on a separate socket
+# and DB under .dev/ (gitignored). Point a dev Neovim at it with:
+#
+#   HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
+#
+# (the plugin reads those envs), so dev edits never reach the installed store.
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+mkdir -p .dev
+
+SOCK="$ROOT/.dev/hephd.sock"
+DB="$ROOT/.dev/heph.db"
+
+echo "dev hephd → socket $SOCK"
+echo "           db     $DB"
+echo "point a dev nvim at it:  HEPH_SOCKET=$SOCK HEPH_DB=$DB nvim"
+echo
+
+exec cargo run -p hephd -- --mode local --socket "$SOCK" --db "$DB"