@vkmikc/create-vkm-kit 4.2.0

package/LICENSE.md

@@ -0,0 +1,44 @@
+# Licencia de libre uso con atribución obligatoria — obsidian-memory-kit
+
+_(Basada en la Licencia MIT, con una condición adicional de atribución visible.
+Based on the MIT License, with one additional visible-attribution condition.)_
+
+Copyright (c) 2026 Jorge David Hidalgo Oporta («Vahlame») — <vahlame@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. **Mandatory visible attribution / Atribución visible obligatoria:** any
+   copy, use, fork, or derivative work of this project must display the
+   visible attribution
+
+   **«© Jorge David Hidalgo Oporta (Vahlame) — kit de memoria original»**
+
+   together with a link to the original repository
+   (<https://github.com/Vahlame/obsidian-memory-kit>), for example in the
+   README or equivalent primary documentation.
+
+   _En español: toda copia, uso, fork o derivado de este proyecto debe incluir
+   la atribución visible indicada arriba junto con el enlace al repositorio
+   original, por ejemplo en el README o documentación principal equivalente._
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+_Este es el único proyecto de Vahlame de libre uso; todos los demás son
+propietarios y todo uso se acuerda directamente con el titular:
+<vahlame@gmail.com> · (+506) 8610-8287._

package/README.md

@@ -0,0 +1,148 @@
+# @vkmikc/create-vkm-kit
+
+Interactive initializer for **Obsidian-style, file-based agent memory** — a Markdown vault your
+AI coding agent reads and writes across sessions, wired to your IDE over **MCP**.
+
+It configures the [`basic-memory`](https://github.com/basicmachines-co/basic-memory) MCP server
+(and, optionally, the `obsidian-memory-hybrid` retrieval sidecar — **BM25 + semantic + graph-aware**
+search with opt-in precision levers (**cross-encoder reranker**, type-weighted graph, importance,
+MMR diversification, passage-window), a **structured knowledge graph** (typed relations + categorized
+observations), **memory reports** for hygiene, and an optional **sqlite-vec** acceleration) for
+**Codex CLI**, **Claude Code** and/or **Cursor**, points it at your vault, and can build the local
+search index — in one
+command. `--full` turns **all** of it on by default.
+
+Part of the [obsidian-memory-kit](https://github.com/Vahlame/obsidian-memory-kit)
+kit. Full docs (English + Spanish), architecture and ADRs live there.
+
+## Quick start
+
+```bash
+# Interactive wizard (pre-selects everything)
+npm create @vkmikc/vkm-kit@latest
+
+# ⚡ The whole stack, zero questions — vault defaults to ~/Documents/obsidian-memory-vault.
+# FULL by default (hybrid + semantic + sqlite-vec + index + rules). Run from a clone of
+# the kit (or add --repo-root <clone>) for the hybrid pieces; degrades to basic-memory otherwise.
+npx @vkmikc/create-vkm-kit@latest -y
+
+# …or point it at any folder (created if it doesn't exist)
+npx @vkmikc/create-vkm-kit@latest ./my-vault -y
+
+# Just plain basic-memory, nothing else:
+npx @vkmikc/create-vkm-kit@latest ./my-vault -y --minimal
+```
+
+The old npm name still works: `npx @vkmikc/create-obsidian-memory` is a shim that forwards to the new package.
+
+**The install is the full stack BY DEFAULT (default since v3.8.1)** — hybrid + semantic + sqlite-vec + index +
+rules, the same set `--full` ships. That wires the knowledge graph + memory reports (automatic once
+hybrid is on), neural embeddings, and the sqlite-vec acceleration. Run it from a clone of the kit (or
+pass `--repo-root <clone>`) to get the hybrid pieces; with no clone it **degrades to `basic-memory`
+instead of aborting**, so a bare `npx` is always safe. `--full` (alias `--all`) is the same full stack
+but also flips `--ide` to `codex,claude`. Use **`--minimal`** for plain `basic-memory`, or
+`--no-<piece>` (e.g. `--no-semantic`, `--no-vec`) to drop one part.
+
+The wizard asks for your vault path and which IDE(s) to wire; the `-y` form skips all prompts. Either
+way it writes the MCP config and scaffolds a starter vault (`START_HERE.md`, `MEMORY.md`, `PROJECTS/`,
+`SESSION_LOG.md`, `PRACTICES/`, `STACKS/`, `_meta/agent-profiles.md`).
+
+## One-command, non-interactive (CI / fresh PC)
+
+```bash
+# Codex CLI + Claude Code, hybrid search + multilingual embeddings, backend installed,
+# index built, rules written — everything, from a kit clone:
+node packages/create-vkm-kit/src/index.js --full --vault "$HOME/my-vault" --repo-root .
+
+# …or spell it out (and add cursor) instead of --full:
+node packages/create-vkm-kit/src/index.js --non-interactive \
+  --vault "$HOME/my-vault" --ide codex,claude,cursor \
+  --with-hybrid --semantic --install-backend --build-index --rules all --repo-root .
+```
+
+`--with-hybrid` (and `--full`'s hybrid step) needs a local clone of the kit — it wires the Node
+bridge + Python backend — so run it from the clone or pass `--repo-root <clone>`. The plain
+`basic-memory` path needs no clone, and `--full` falls back to it (with a warning) if no clone is
+found.
+
+## Options
+
+| Flag                               | Purpose                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--lang en`                        | English prompts (default is Spanish-first).                                                                                                                                                                                                                                                                                                                        |
+| `--full`, `--all`                  | **One-shot max power, every feature on (implies `-y`).** Defaults `--ide` to `codex,claude`; turns on `--with-hybrid --semantic --vec --build-index --install-backend --obscura` + rules per agent. Degrades to `basic-memory` (no abort) without a kit clone. Opt out: `--no-semantic` / `--no-vec` / `--no-build-index` / `--no-install-backend` / `--no-rules`. |
+| `--dry-run`                        | Print what would be written — no writes.                                                                                                                                                                                                                                                                                                                           |
+| `-y`, `--yes`, `--non-interactive` | Headless mode (no prompts).                                                                                                                                                                                                                                                                                                                                        |
+| `[vault]` (positional)             | Vault path as the first argument (e.g. `… ./my-vault -y`); same as `--vault`.                                                                                                                                                                                                                                                                                      |
+| `--vault <path>`                   | Vault root (absolute or cwd-relative). Optional — defaults to `~/Documents/obsidian-memory-vault`, created if missing.                                                                                                                                                                                                                                             |
+| `--ide <list>`                     | IDEs to wire, comma-separated: `codex`, `claude`, `cursor` (default: `cursor`; with `--full`: `codex,claude`).                                                                                                                                                                                                                                                     |
+| `--no-cursor-mcp`                  | Skip writing `~/.cursor/mcp.json`.                                                                                                                                                                                                                                                                                                                                 |
+| `--no-git-init`                    | Skip `git init` when the vault has no `.git`.                                                                                                                                                                                                                                                                                                                      |
+| `--with-hybrid`                    | Also wire `obsidian-memory-hybrid` (needs a kit clone; use `--repo-root` or cwd walk).                                                                                                                                                                                                                                                                             |
+| `--repo-root <path>`               | Root of the `obsidian-memory-kit` clone (hybrid bridge + Python source).                                                                                                                                                                                                                                                                                           |
+| `--semantic`                       | With `--with-hybrid`: neural embeddings (fastembed multilingual; needs the `[semantic]` extra).                                                                                                                                                                                                                                                                    |
+| `--vec`                            | With `--with-hybrid`: sqlite-vec acceleration (needs the `[vec]` extra; sets `OBSIDIAN_MEMORY_SQLITE_VEC=1`). Ranking-identical with a safe fallback. On under `--full`; opt out with `--no-vec`.                                                                                                                                                                  |
+| `--rerank`                         | With `--with-hybrid`: cross-encoder reranker for a top-k precision boost (installs the `[rerank]` extra; sets `OBSIDIAN_MEMORY_RERANK=1`). **Opt-in only** — downloads a model on first use and needs a content-language-matched model (the multilingual default); **not** enabled by `--full`.                                                                    |
+| `--build-index`                    | After wiring, build the local FTS (+ semantic) index (needs the Python backend).                                                                                                                                                                                                                                                                                   |
+| `--install-backend`                | `pip install -e` the Python RAG backend (best-effort; on by default under `--full`).                                                                                                                                                                                                                                                                               |
+| `--with-gitleaks`                  | Install a gitleaks pre-commit hook in `<vault>/.git/hooks/`.                                                                                                                                                                                                                                                                                                       |
+| `--rules <list>`                   | Install the memory-rules block into `claude` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `agents` (`./AGENTS.md`), `cursor` (`.cursor/rules`). Or `all` / `none`. Idempotent; never clobbers your content. Headless writes nothing unless passed (or `--full`); interactive asks.                                                                     |
+| `--no-rules`                       | Don't write any rules file.                                                                                                                                                                                                                                                                                                                                        |
+| `--native-memory-override`         | (Claude Code) Force the native-memory override on, even under `--minimal`.                                                                                                                                                                                                                                                                                         |
+| `--no-native-memory-override`      | (Claude Code) Leave Claude's native auto-memory untouched (don't write `autoMemoryEnabled:false` / the SessionStart hook).                                                                                                                                                                                                                                         |
+| `--help`                           | Show usage.                                                                                                                                                                                                                                                                                                                                                        |
+| `--obscura`, `--no-obscura`        | Install + wire **obscura-web** (stealth `obscura_fetch` + robust `obscura_search`); **on under `--full`**. Needs a kit clone; downloads + SHA-256-verifies the pinned obscura binary into `~/.vkm/obscura/`. See [ADR-0051](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0051-obscura-web-stealth-browser.md).                                |
+| `--searxng-url <url>`              | Point `obscura_search` at a SearXNG JSON instance directly (bypasses the on-demand manager — e.g. a remote / Docker SearXNG).                                                                                                                                                                                                                                      |
+
+- `codex` registers servers via the Codex CLI (`codex mcp add` → `~/.codex/config.toml`).
+- `claude` registers servers via the Claude Code CLI (`claude mcp add -s user`).
+- `cursor` writes `~/.cursor/mcp.json`.
+
+### Install the memory rules too
+
+The initializer can also drop the **memory-protocol rules** (how the agent should use the vault), not just the MCP wiring. Use `--rules all` for full coverage:
+
+```bash
+npx @vkmikc/create-vkm-kit@latest ./my-vault -y --ide cursor,claude --rules all
+```
+
+It writes an **idempotent marked block** (`<!-- obsidian-memory:start --> … <!-- obsidian-memory:end -->`) into `~/.claude/CLAUDE.md`, `./AGENTS.md` and `.cursor/rules/obsidian-memory.mdc`, merging in place — **your own content is never touched**, and re-runs just refresh the block. Cursor's _global_ User Rules can't be auto-written (not a file), so paste that one from the install guide.
+
+### Make the vault Claude Code's _only_ memory (`--ide claude`)
+
+Claude Code ships a **native auto-memory** (`~/.claude/projects/<path>/memory/MEMORY.md`) that the harness auto-loads and the base prompt tells the model to `Write` to. Left on, it competes with — and by default beats — the vault, especially while the `vault_*` MCP tools are deferred. So a Claude Code install also, **by default** (ADR-0029):
+
+1. Writes `"autoMemoryEnabled": false` into `~/.claude/settings.json` (idempotent merge — other keys/hooks are preserved; invalid JSON is backed up and skipped).
+2. Installs a cross-platform Node **`SessionStart` hook** (`~/.claude/hooks/session-start-vault-context.mjs`) that injects the vault map + reinforced reminders: vault is the only source of truth, first step is to `ToolSearch`-load deferred `vault_*` tools, recall = `vault_hybrid_search`, and the close ritual (`SESSION_LOG.md` + `PROJECTS/<project>.md`, each edit anchored on one CRLF line).
+
+Re-runs don't duplicate the hook (a legacy `.ps1` variant is recognized and replaced). Opt out with `--minimal` or `--no-native-memory-override`; force on with `--native-memory-override`.
+
+## What the installed memory does
+
+Beyond wiring the MCP, the kit installs a **memory protocol** (the rules block above) and scaffolds a vault designed to get smarter over time while staying token-cheap:
+
+- **Passage-first recall** — the agent pulls the matching _section_ of a note (`vault_hybrid_search`), not the whole file, and checks the vault _before answering_ when a task continues prior work or names a known project/person/tool.
+- **Graph-aware recall + autocomplete (v3.5)** — `vault_hybrid_search` can follow your `[[wikilinks]]` (opt-in `graph: true`), so a note linked from a strong hit surfaces even when its own words barely match; `vault_complete` resolves a prefix to the titles / filenames / `#tags` that exist. See [how it works](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/en/how-it-works.md#the-retrieval-stack-at-a-glance-old--new).
+- **Measured, not just claimed (v3.7)** — retrieval quality is benchmarked against a fixed labelled corpus and gated in CI (recall@k / MRR / hit@1), so a recall regression fails the build instead of shipping silently. A missing or misspelled term also no longer drops a relevant note (lexical search falls back from strict AND to OR). See [`evals/retrieval`](https://github.com/Vahlame/obsidian-memory-kit/tree/main/evals/retrieval).
+- **Structured knowledge graph (v3.8)** — typed relations (`- implements [[adr-0014]]`) and categorized observations (`- [decision] … #tag`) authored in plain Markdown (Basic-Memory-compatible) become queryable: `vault_relations` answers "what supersedes this / what links here?" both directions, `vault_observations` pulls every `[decision]` or `#tag` across the vault, and `vault_kg_suggest` proposes structure for a note (read-only — you confirm and edit). See [ADR-0023](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0023-structured-knowledge-graph.md).
+- **Memory reports (v3.8)** — `vault_memory_report` is a read-only digest for periodic upkeep: automatic indices (observations by category, graph hub notes, top `#tags`), hygiene (oversized / stale / orphan notes, broken links, `SESSION_LOG` bloat) with concrete next steps, and opt-in near-duplicate pairs to review. It flags what to condense; it never rewrites a note. See [ADR-0024](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0024-memory-reports-and-compaction.md).
+- **sqlite-vec acceleration (v3.8, opt-in, on under `--full`)** — for large vaults, the cosine scan runs inside SQLite over the same index file via the sqlite-vec extension; ranking is **identical** to the pure-Python path (verified by the bench + a parity test) with a transparent fallback. The in-file embedded answer — no Chroma/LanceDB server. See [ADR-0025](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0025-optional-sqlite-vec-acceleration.md).
+- **Opt-in precision levers (v3.9)** — `vault_hybrid_search` gains default-off knobs that only ever reorder the fused candidates, never break search: a **cross-encoder reranker** (`rerank: true`, behind the `[rerank]` extra / `--rerank`; re-scores query + passage _together_ — the precision lever, and only helps with a strong, content-language-matched model), **type-weighted graph recall** (`graphTyped: true`, verb-weighted typed relations), **importance** (`importance: true`, in-degree/hub bias), **MMR** diversification (`mmr: true`), and **passage-window** expansion (`passageWindow: N`). The measured default path stays byte-identical. See [ADR-0026](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0026-cross-encoder-reranker.md) / [ADR-0027](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0027-type-weighted-graph-and-importance.md) / [ADR-0028](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/adr/0028-mmr-and-passage-window.md).
+- **Self-check** — before non-trivial answers it sanity-checks its own assumptions and edge cases (scaled to the task, internal — no padding).
+- **Coach, don't impose** — flags high-impact anti-patterns in your code as a _question_ and logs them to `PRACTICES/observations.md`; promotes to `confirmed-{good,bad}.md` only when you confirm.
+- **Evolving memory** — records new tech in `STACKS/`, firm preferences in `MEMORY.md`, hypotheses → facts.
+- **Model-aware** — reads `_meta/agent-profiles.md` to tune behavior to the active model's strengths (Claude, Cursor Composer, GPT, DeepSeek, Gemini…) and learns which model fits which task over time.
+- **Token economy** — all of the above is bounded by passage-first reads, terse bullets and dedup, so smarter ≠ pricier.
+
+Read the rules block before installing — it's printed in [`docs/en/install.md`](https://github.com/Vahlame/obsidian-memory-kit/blob/main/docs/en/install.md) (Step 4) and is what `--rules` writes (idempotently) into your agent configs.
+
+## Requirements
+
+- **Node.js ≥ 20**
+- **[`uv`](https://docs.astral.sh/uv/)** (for `uvx basic-memory mcp`)
+- For `--with-hybrid` / `--build-index` / `--install-backend`: **Python ≥ 3.11** + `pip`, and a clone of the kit (`obsidian-memory-rag`).
+- For `--ide claude`: the **Claude Code** CLI on `PATH`. For `--ide codex`: the **Codex** CLI on `PATH` (otherwise the installer prints the `codex mcp add` command + a `config.toml` block to paste).
+
+## License
+
+Free use with mandatory visible attribution (MIT-based) — © Vahlame. See [`LICENSE.md`](./LICENSE.md) and the [repository](https://github.com/Vahlame/obsidian-memory-kit) for details.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vkmikc/create-vkm-kit",
+  "version": "4.2.0",
+  "description": "vkm-kit installer: persistent Markdown+git memory for AI agents (MCP) with hybrid search, stealth web fetch/search (obscura + on-demand SearXNG), a cross-domain execution-discipline skill, token-saver hooks, a local usage doctor and a spec-builder — one npx command.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://github.com/Vahlame/create-vkm-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vahlame/create-vkm-kit.git",
+    "directory": "packages/create-vkm-kit"
+  },
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "cursor",
+    "claude-code",
+    "codex",
+    "agent-memory",
+    "ai-memory",
+    "basic-memory",
+    "rag",
+    "semantic-search",
+    "hybrid-search",
+    "knowledge-graph",
+    "web-search",
+    "web-fetch",
+    "stealth-browser",
+    "obscura",
+    "searxng",
+    "token-efficiency",
+    "vkm"
+  ],
+  "files": [
+    "src",
+    "templates"
+  ],
+  "type": "module",
+  "bin": {
+    "create-vkm-kit": "src/index.js",
+    "vkm": "src/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "execa": "^9.5.2",
+    "fs-extra": "^11.2.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/asset-install.mjs

@@ -0,0 +1,109 @@
+// Managed-asset installer for the template files this kit copies into the user's Claude
+// Code profile (output styles, skills, subagent templates) — anything that is a FILE the
+// kit owns rather than a key inside settings.json.
+//
+// Ownership is tracked in a sidecar manifest (`~/.claude/vkm-kit.assets.json`) that records
+// the SHA-256 of every file AS INSTALLED. That gives uninstall a stronger guarantee than
+// the hooks' marker-string check: a file is deleted only when its current content hash still
+// equals the recorded one — a user who edited an installed template keeps their file (with a
+// skip report), and a file we never recorded is never touched at all. Install always
+// overwrites (kit templates are kit-owned, same policy as the hook scripts; users who want
+// to customize should copy under a different name).
+//
+// No logging here — functions return action reports ({installed, removed, skipped}) and the
+// orchestrator owns the console. All I/O goes through the same crash-safe primitives as the
+// rest of the installer (`atomicWriteJson` for the sidecar; copy is per-file so a failure
+// leaves previous files intact).
+import crypto from "node:crypto";
+import path from "node:path";
+import fse from "fs-extra";
+import { atomicWriteJson, readSettingsSafe } from "./settings-io.mjs";
+
+/** Sidecar manifest basename, kept under `~/.claude/`. */
+export const ASSETS_SIDECAR_BASENAME = "vkm-kit.assets.json";
+
+function sha256(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Load the sidecar manifest (missing/corrupt → empty manifest; never throws). */
+async function readSidecar(sidecarFp) {
+  const { existing, invalidJson } = await readSettingsSafe(sidecarFp);
+  if (invalidJson || typeof existing.assets !== "object" || existing.assets === null) {
+    return { version: 1, assets: {} };
+  }
+  return { version: 1, assets: { ...existing.assets } };
+}
+
+/** Persist the manifest; deletes the file entirely when no assets remain (no trace). */
+async function writeSidecar(sidecarFp, manifest) {
+  if (Object.keys(manifest.assets).length === 0) {
+    await fse.remove(sidecarFp);
+    return;
+  }
+  await atomicWriteJson(sidecarFp, manifest);
+}
+
+/**
+ * Copy each `{src, dest}` pair into place and record its content hash in the sidecar.
+ * Overwrites existing files (kit-owned templates); re-runs converge on the same state.
+ * @param {object} opts
+ * @param {{ src: string, dest: string }[]} opts.files - absolute paths
+ * @param {string} opts.sidecarFp - absolute path of the sidecar manifest
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{ installed: string[] }>} dest paths written (or that would be)
+ */
+export async function installManagedAssets({ files, sidecarFp, dryRun = false }) {
+  const installed = [];
+  if (dryRun) {
+    return { installed: files.map((f) => f.dest) };
+  }
+  const manifest = await readSidecar(sidecarFp);
+  for (const { src, dest } of files) {
+    const bytes = await fse.readFile(src);
+    await fse.ensureDir(path.dirname(dest));
+    await fse.copy(src, dest, { overwrite: true });
+    manifest.assets[dest] = { hash: sha256(bytes), installedAt: new Date().toISOString() };
+    installed.push(dest);
+  }
+  await writeSidecar(sidecarFp, manifest);
+  return { installed };
+}
+
+/**
+ * Remove managed assets: every file recorded in the sidecar (optionally narrowed to
+ * `dests`) is deleted IFF its current content hash still equals the recorded one. Modified
+ * files are skipped (and reported) but their manifest entry is dropped either way — after an
+ * uninstall the kit no longer claims them. Missing files just drop their entry.
+ * @param {object} opts
+ * @param {string} opts.sidecarFp
+ * @param {string[]} [opts.dests] - narrow removal to these dest paths (default: all recorded)
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{ removed: string[], skipped: string[] }>}
+ */
+export async function removeManagedAssets({ sidecarFp, dests, dryRun = false }) {
+  const manifest = await readSidecar(sidecarFp);
+  const targets = dests ?? Object.keys(manifest.assets);
+  const removed = [];
+  const skipped = [];
+  for (const dest of targets) {
+    const entry = manifest.assets[dest];
+    if (!entry) continue;
+    let unmodified = false;
+    try {
+      unmodified = sha256(await fse.readFile(dest)) === entry.hash;
+    } catch {
+      // Missing/unreadable: nothing to delete; just release the claim below.
+      unmodified = false;
+    }
+    if (unmodified) {
+      if (!dryRun) await fse.remove(dest);
+      removed.push(dest);
+    } else if (await fse.pathExists(dest)) {
+      skipped.push(dest);
+    }
+    if (!dryRun) delete manifest.assets[dest];
+  }
+  if (!dryRun) await writeSidecar(sidecarFp, manifest);
+  return { removed, skipped };
+}