@avantf/dsh-mem 0.1.1 → 0.2.0

package/lib/index.js

@@ -1,11 +1,11 @@
 import { createRequire } from "node:module";
 import { accessSync, chmodSync, constants, copyFileSync, createWriteStream, existsSync, mkdirSync, promises, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
-import z from "@deepseek-ai/schemastery";
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { basename, delimiter, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
-import { z as z$1 } from "zod";
+import { z } from "zod";
 import { homedir } from "node:os";
+import z$1 from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { isSeq, parse, parseDocument } from "yaml";
 import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
@@ -13,121 +13,16 @@ import { pipeline } from "node:stream/promises";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createInflateRaw } from "node:zlib";
 import Database from "better-sqlite3";
-import { readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-//#region lib/types/prompt.js
-/**
-* The two system-prompt sections this plugin contributes (DESIGN §10).
-*
-* They exist for something a tool description cannot carry: a description says what a call DOES,
-* never when to reach for it unprompted, and the default behaviour is to wait until asked. So each
-* says only WHEN its store is worth writing or reading. Neither says anything about how memory is
-* retained — that stays out of every model-facing string, held to the contract's
-* `RETENTION_VOCABULARY`, the same list the tool descriptions are held to.
-*
-* The knowledge one is the section whose ABSENCE was measured: a user had just ingested
-* 《Cgroup v2 技术综述》(which answers "cgroup v2 的内存保护" at score 1.0) and asked about it in a
-* session whose prompt named only the memory tools, so the model never looked. A tool description
-* cannot fix that by itself — `kb_query`'s says what the call does and even leads with 记忆 facts,
-* which reads as a memory tool — and the model cannot know the library is relevant to a question
-* without being told to check it. Hence the "先检索一次再作答" nudge, plus the explicit
-* "你看不到库里有什么" clause: the thing that made the miss invisible is that nothing in the
-* prompt acknowledged the store existed at all.
-*
-* `order` 3000/3010 are third-party slots: after the harness's per-tool guidance block (1000–2900)
-* and before its toolset-level guidance (5000). They are not repository-owned placements, so they
-* do not resolve through `getSectionOrder`.
-*
-* The sections say WHAT TO DO and never WHY. The reasoning behind each rule is measured and
-* lives here, in DESIGN §10 and in the CHANGELOG — not in the prompt, where it costs tokens on
-* every step and does not change the action.
-*
-* Kept in its own module — not in `index.ts` — so the text can be read and checked without the
-* plugin entry's `@deepseek-ai/*` runtime imports, which resolve only in a harness workspace.
-*/
-const MEMORY_PROMPT_SECTION = {
-	name: "avantf:memory-usage",
-	order: 3e3,
-	text: "记忆（`mem_remember`）：把**重要且跨会话仍成立**的事实主动记下来——用户偏好、项目决策、环境约束、接口约定、踩过的坑。同一事实的修正用 `update`，一句自包含的陈述。不要记录临时聊天内容、一次性任务的中间状态、能直接从代码或文档读到的内容。"
-};
-/**
-* WHEN to consult the document knowledge base. See the module comment for why this is a separate
-* section rather than a clause inside the memory one: the two stores answer different questions,
-* and a session that needs the knowledge base may have no memory question at all.
-*/
-const KNOWLEDGE_PROMPT_SECTION = {
-	name: "avantf:knowledge-usage",
-	order: 3010,
-	text: "知识库（`kb_query` / `kb_add`）存放**用户提供的成篇资料**：文档、长说明、规范、综述等要按原文查阅的内容。回答涉及已入库资料的问题之前，先用 `kb_query` 检索；命中就按 `source_ref` 引用原文。用户给了值得长期留存的成篇内容就主动 `kb_add` 入库；一句话的事实属于记忆（`mem_remember`），不要入知识库。"
-};
-/**
-* HOW to change a document that is already in the library.
-*
-* A separate section because it is a different job from the one above, and because the first
-* section is already at 382 of its 400-character budget. It exists to prevent a measured failure:
-* asked to "update the knowledge base", a model called the old all-in-one tool with a NEW title and
-* silently created a sibling document (《… · 补遗》) while the original stayed behind — two
-* overlapping documents, and the reader left to reconcile them. Changing a document is a FILE EDIT,
-* so the section has to name the file tools and warn about the one that destroys the frontmatter.
-*/
-const KB_EDIT_PROMPT_SECTION = {
-	name: "avantf:kb-edit",
-	order: 3020,
-	text: "更新知识库时，要在原文上修改或追加，不要新建一个补充文档。用 `kb_list` 拿到受管 `.md` 的绝对路径，用文件工具修改。在用户明确要求时使用 `kb_remove` 删除。"
-};
-//#endregion
-//#region lib/types/hints.js
-/**
-* The plugin's CONDITIONAL hints: one line per store, contributed only when that store already
-* holds something relevant to what the user just sent (DESIGN §12).
-*
-* These are deliberately NOT part of the always-on usage sections. A usage section says WHEN a
-* store is worth consulting and therefore has to be paid for on every step of every session; this
-* says "there is something here, right now", which is only true sometimes. The two layers compose:
-* the section is the fallback for the paraphrase the lexical probe misses, and the hint is the
-* concrete nudge for the case it catches.
-*
-* ONE LINE PER STORE, never a merged sentence. The two stores answer different questions and
-* either can be the relevant one, so `RelevanceHit` is a closed four-valued answer and each store
-* gets its own contribution — a caller can then see, and later tune or drop, one without the other.
-*
-* WHY EACH LINE NAMES THE PLUGIN. This text is injected as runtime context, and the harness
-* materialises that as a USER-role snapshot in the conversation (`dsh-agent-loop`'s
-* `runtimeContext.project`). Without an author, a line like "记忆里有相关内容" reads as something
-* the user said. The `[avantf-mem 插件]` prefix is what keeps the provenance honest.
-*/
-const MEMORY_HINT = "[avantf-mem 插件] 记忆里有与本次提问相关的事实；需要时用 `mem_recall` 检索。";
-const KNOWLEDGE_HINT = "[avantf-mem 插件] 知识库里有与本次提问相关的内容；需要时用 `kb_query` 检索。";
-/**
-* Map one answer to the two contributions, as text.
-*
-* An empty string is the "contribute nothing" value: `renderPrompt`/`renderContextSections` drop
-* empty text, so `none` (and the missing half of `memory`/`knowledge`) costs no tokens at all.
-*/
-function hintLines(hit) {
-	return {
-		memory: hit === "memory" || hit === "both" ? MEMORY_HINT : "",
-		knowledge: hit === "knowledge" || hit === "both" ? KNOWLEDGE_HINT : ""
-	};
-}
-/**
-* The plain text of an inbox message, or `''` when it carries none.
-*
-* `dsh-agent-loop`'s own extractor returns `undefined` unless the message is exactly ONE text
-* block; a steered or multi-part message would then silently produce no hint. Concatenating the
-* text blocks keeps the probe working for those, and non-text blocks (images) are simply skipped —
-* the probe is lexical, so it has nothing to say about them anyway.
-*/
-function messageText(message) {
-	const content = message?.content;
-	if (!Array.isArray(content)) return "";
-	return content.map((block) => {
-		const b = block;
-		return b?.type === "text" && typeof b.text === "string" ? b.text : "";
-	}).filter(Boolean).join("\n");
-}
-//#endregion
 //#region ../contract/lib/types.js
+/** Shared domain types for avantf-mem. Single source of truth in @avantf/mem-contract. */
+const CATEGORY_VALUES = [
+	"user_pref",
+	"user_env",
+	"project",
+	"tool",
+	"general"
+];
 /**
 * The fact statuses a caller may filter by, as the ONE list every surface reads: the tool schema's
 * `z.enum`, the derived MCP inputSchema and DSH parameter spec, and the CLI's `--status` flag (which
@@ -187,26 +82,26 @@ const DEGRADED_WEIGHTS = {
 * window); a positive value is clamped to it. Past the window transformers.js truncates
 * with no error, so the adapter bounds the text first and warns once (DESIGN §20).
 */
-const maxInputTokens = z$1.number().int().nonnegative().default(0);
-const semanticSchema = z$1.object({
-	backend: z$1.string().default("local_bge"),
-	local_model: z$1.string().default("Xenova/bge-small-zh-v1.5"),
-	dim: z$1.number().int().positive().default(512),
+const maxInputTokens = z.number().int().nonnegative().default(0);
+const semanticSchema = z.object({
+	backend: z.string().default("local_bge"),
+	local_model: z.string().default("Xenova/bge-small-zh-v1.5"),
+	dim: z.number().int().positive().default(512),
 	max_input_tokens: maxInputTokens,
-	mirror: z$1.string().default("https://hf-mirror.com"),
-	cache_dir: z$1.string().default("~/.avantf/models"),
-	auto_download: z$1.boolean().default(true)
+	mirror: z.string().default("https://hf-mirror.com"),
+	cache_dir: z.string().default(""),
+	auto_download: z.boolean().default(true)
 });
-const rerankSchema = z$1.object({
-	backend: z$1.string().default("none"),
-	local_model: z$1.string().default("Xenova/bge-reranker-base"),
+const rerankSchema = z.object({
+	backend: z.string().default("none"),
+	local_model: z.string().default("Xenova/bge-reranker-base"),
 	max_input_tokens: maxInputTokens,
-	mirror: z$1.string().default("https://hf-mirror.com"),
-	cache_dir: z$1.string().default("~/.avantf/models"),
-	auto_download: z$1.boolean().default(true)
+	mirror: z.string().default("https://hf-mirror.com"),
+	cache_dir: z.string().default(""),
+	auto_download: z.boolean().default(true)
 });
-const vectorStoreSchema = z$1.object({
-	backend: z$1.string().default("auto"),
+const vectorStoreSchema = z.object({
+	backend: z.string().default("auto"),
 	/**
 	* Vector counts at which `backend: auto` migrates to an ANN index.
 	*
@@ -220,9 +115,9 @@ const vectorStoreSchema = z$1.object({
 	* sub-millisecond. At 8000 recall falls to 0.89, so for a larger corpus raise
 	* `hnswlib_ef_search` (or accept the loss) instead of moving this threshold.
 	*/
-	auto_thresholds: z$1.object({
-		hnswlib: z$1.number().int().positive().default(2e3),
-		faiss: z$1.number().int().positive().default(1e5)
+	auto_thresholds: z.object({
+		hnswlib: z.number().int().positive().default(2e3),
+		faiss: z.number().int().positive().default(1e5)
 	}).default({
 		hnswlib: 2e3,
 		faiss: 1e5
@@ -234,20 +129,20 @@ const vectorStoreSchema = z$1.object({
 	* ~3 ms at n=2000). Recall falls as the corpus grows, so raise this before raising
 	* `auto_thresholds.hnswlib`. The store uses `max(ef_search, 8 × k)`.
 	*/
-	hnswlib_ef_search: z$1.number().int().min(16).max(2048).default(256)
+	hnswlib_ef_search: z.number().int().min(16).max(2048).default(256)
 });
-const retrieverSchema = z$1.object({
-	weight_semantic: z$1.number().min(0).max(1).default(.55),
-	weight_fts: z$1.number().min(0).max(1).default(.3),
-	weight_jaccard: z$1.number().min(0).max(1).default(.15),
+const retrieverSchema = z.object({
+	weight_semantic: z.number().min(0).max(1).default(.55),
+	weight_fts: z.number().min(0).max(1).default(.3),
+	weight_jaccard: z.number().min(0).max(1).default(.15),
 	/**
 	* Token budget for a retrieval RESULT (`0` = unlimited). `limit` bounds how many hits, never
 	* how much text, so a broad query could otherwise pour tens of thousands of characters into a
 	* model's context while a narrow one poured in a paragraph (DESIGN §20). Hits shortened by the
 	* budget are marked `truncated`.
 	*/
-	max_output_tokens: z$1.number().int().nonnegative().default(8e3),
-	over_fetch_factor: z$1.number().int().positive().default(5),
+	max_output_tokens: z.number().int().nonnegative().default(8e3),
+	over_fetch_factor: z.number().int().positive().default(5),
 	/**
 	* Rows one non-semantic retrieval leg may hand to fusion (`0` = derived: `max(200, 4×overFetch)`).
 	*
@@ -261,59 +156,59 @@ const retrieverSchema = z$1.object({
 	* spend less memory than lose the tail: it is `retriever.leg_cap` that makes the cap a
 	* measurable variable instead of a constant baked into the store.
 	*/
-	leg_cap: z$1.number().int().nonnegative().default(0)
+	leg_cap: z.number().int().nonnegative().default(0)
 });
 /**
 * Trust & forgetting (TRUST_MODEL.md). The aging clock is the ACTIVE-DAY counter
 * (`avantf_stats.trust_clock`), not wall time: downtime counts as at most
 * `presence.gap_cap_days` so a shut-down system never "starves" its memories.
 */
-const presenceSchema = z$1.object({
-	mode: z$1.enum(["process"]).default("process"),
+const presenceSchema = z.object({
+	mode: z.enum(["process"]).default("process"),
 	/** One presence advances the clock by at most this many days (downtime ⇒ 1 day). */
-	gap_cap_days: z$1.number().min(0).default(1),
+	gap_cap_days: z.number().min(0).default(1),
 	/** Long-lived surfaces (plugin / MCP) tick this often; 0 = startup pass only. */
-	heartbeat_minutes: z$1.number().int().nonnegative().default(60)
+	heartbeat_minutes: z.number().int().nonnegative().default(60)
 });
-const trustSchema = z$1.object({
+const trustSchema = z.object({
 	/** false = no presence, no decay, no reinforcement, no pinning (TTL/idle/purge keep running). */
-	enabled: z$1.boolean().default(true),
+	enabled: z.boolean().default(true),
 	/** Initial trust of a new fact. */
-	start: z$1.number().min(0).max(1).default(.5),
+	start: z.number().min(0).max(1).default(.5),
 	/** Linear decay per active day: `0.5 / 90` ⇒ 90 active days from start to 0. */
-	decay_per_day: z$1.number().min(0).max(1).default(.5 / 90),
+	decay_per_day: z.number().min(0).max(1).default(.5 / 90),
 	/** Trust ≤ this ⇒ forgotten (archived 'forgot'). 0 = "reaching zero is forgetting". */
-	forget_threshold: z$1.number().min(0).max(1).default(0),
+	forget_threshold: z.number().min(0).max(1).default(0),
 	/** Reaching this via explicit feedback promotes to permanent (snapped to 1.0). */
-	permanent_threshold: z$1.number().min(0).max(1).default(.9),
+	permanent_threshold: z.number().min(0).max(1).default(.9),
 	/** A recall of something at/below this raises it straight back to this value. */
-	recall_floor: z$1.number().min(0).max(1).default(.5),
+	recall_floor: z.number().min(0).max(1).default(.5),
 	/** Per-recall gain (before marginal decay). */
-	recall_delta: z$1.number().min(0).max(1).default(.03),
+	recall_delta: z.number().min(0).max(1).default(.03),
 	/** Effective reinforcement events per fact per 24h (R10: zero-gain ones don't count). */
-	recall_daily_cap: z$1.number().int().nonnegative().default(3),
+	recall_daily_cap: z.number().int().nonnegative().default(3),
 	/** 1 = every in-window gain is equal; 0.5 = 0.03 / 0.015 / 0.0075 … */
-	recall_marginal_decay: z$1.number().min(0).max(1).default(1),
+	recall_marginal_decay: z.number().min(0).max(1).default(1),
 	/** Recall alone can never exceed this (and never pins — see D11). */
-	recall_ceiling: z$1.number().min(0).max(1).default(.85),
+	recall_ceiling: z.number().min(0).max(1).default(.85),
 	/** Explicit `helpful` / `unhelpful` step. */
-	feedback_delta: z$1.number().min(0).max(1).default(.05),
+	feedback_delta: z.number().min(0).max(1).default(.05),
 	/** 0 = unlimited; >0 also caps feedback reinforcement per fact per 24h. */
-	feedback_daily_cap: z$1.number().int().nonnegative().default(0),
+	feedback_daily_cap: z.number().int().nonnegative().default(0),
 	/** A revised fact inherits the settled trust (and pin) of the row it replaces. */
-	inherit_trust_on_update: z$1.boolean().default(true),
+	inherit_trust_on_update: z.boolean().default(true),
 	/** Pinned (permanent) facts are never physically purged. */
-	purge_skips_pinned: z$1.boolean().default(true),
+	purge_skips_pinned: z.boolean().default(true),
 	/** Calendar fallback: unused for this many days ⇒ archived 'idle'. */
-	idle_calendar_days: z$1.number().int().positive().default(365),
+	idle_calendar_days: z.number().int().positive().default(365),
 	/** Per-tick budget for the settle sweep (the other sweeps only touch critical rows). */
-	tick_max_facts: z$1.number().int().positive().default(5e3),
+	tick_max_facts: z.number().int().positive().default(5e3),
 	presence: presenceSchema.prefault({})
 });
-const lifecycleSchema = z$1.object({
+const lifecycleSchema = z.object({
 	/** Purge window, measured in ACTIVE days since `archived_clock`. */
-	purge_after_archived_days: z$1.number().int().nonnegative().default(365),
-	contradiction_threshold: z$1.number().min(0).max(1).default(.6)
+	purge_after_archived_days: z.number().int().nonnegative().default(365),
+	contradiction_threshold: z.number().min(0).max(1).default(.6)
 });
 /**
 * External tools and derived runtime state the plugin must PROVIDE, not merely use (DESIGN §13).
@@ -327,21 +222,21 @@ const lifecycleSchema = z$1.object({
 * The mirror list defaults to DOMESTIC proxies, with the official source always tried last — a
 * 35 MB download from GitHub is the difference between a usable first run and an abandoned one.
 */
-const toolsSchema = z$1.object({
+const toolsSchema = z.object({
 	/** Managed install root; `<dir>/<tool>/<version>/bin/<binary>` per artifact. */
-	dir: z$1.string().default("~/.avantf/tools"),
+	dir: z.string().default(""),
 	/** URL templates tried before the official source; `{url}` is the original URL, `{file}` its name. */
-	mirror: z$1.array(z$1.string()).default([
+	mirror: z.array(z.string()).default([
 		"https://ghfast.top/{url}",
 		"https://ghproxy.net/{url}",
 		"https://gh-proxy.com/{url}"
 	]),
 	/** Download a missing artifact at startup. `false` = use only what is already on this machine. */
-	auto_install: z$1.boolean().default(true)
+	auto_install: z.boolean().default(true)
 });
 /** The merged runtime config shared by memory and knowledge stores. */
-const ConfigSchema = z$1.object({
-	dataHome: z$1.string().default("~/.avantf"),
+const ConfigSchema = z.object({
+	dataHome: z.string().default("~/.avantf"),
 	semantic: semanticSchema.prefault({}),
 	rerank: rerankSchema.prefault({}),
 	vectorStore: vectorStoreSchema.prefault({}),
@@ -356,16 +251,7 @@ const defaultConfig = ConfigSchema.parse({});
 * Memory store-specific config. Overrides on top of the common Config.
 * Note: `db.path` is the single authoritative path for the memory DB.
 */
-const MemoryConfigSchema = z$1.object({
-	db: z$1.object({ path: z$1.string().default("") }).prefault({}),
-	category_values: z$1.array(z$1.string()).default([
-		"user_pref",
-		"user_env",
-		"project",
-		"tool",
-		"general"
-	])
-});
+const MemoryConfigSchema = z.object({ db: z.object({ path: z.string().default("") }).prefault({}) });
 /**
 * Ingestion boundary (DESIGN §8 / D5). `kb_ingest`'s `source_uri` is RESOLVED —
 * a local path is read, an http(s) URL is fetched — and everything it reads lands
@@ -373,24 +259,24 @@ const MemoryConfigSchema = z$1.object({
 * read-any-file / probe-the-intranet primitive for a steered agent. Safe by
 * default, with one explicit opt-in per resource kind.
 */
-const ingestSchema = z$1.object({
+const ingestSchema = z.object({
 	/** Roots a local `source_uri`/`kb_import` path may be read from; empty ⇒ the process workspace (`cwd`). */
-	local_roots: z$1.array(z$1.string()).default([]),
+	local_roots: z.array(z.string()).default([]),
 	/** Lift the roots check entirely — read any local path. */
-	allow_outside_workspace: z$1.boolean().default(false),
+	allow_outside_workspace: z.boolean().default(false),
 	/** Allow `http(s)` fetches to loopback/private/link-local addresses. */
-	allow_private_network: z$1.boolean().default(false)
+	allow_private_network: z.boolean().default(false)
 });
 /** Knowledge store-specific config. */
-const KnowledgeConfigSchema = z$1.object({
-	db: z$1.object({ path: z$1.string().default("") }).prefault({}),
+const KnowledgeConfigSchema = z.object({
+	db: z.object({ path: z.string().default("") }).prefault({}),
 	/**
 	* The managed document directory: one editable `.md` per document, holding the body the KB
 	* indexed. Empty ⇒ `<dataHome>/knowledge/docs`. It holds a COPY, never the origin: a
 	* `source_uri` is read once at ingest, so editing or deleting these files cannot touch
 	* whatever the document came from.
 	*/
-	docs: z$1.object({ dir: z$1.string().default("") }).prefault({}),
+	docs: z.object({ dir: z.string().default("") }).prefault({}),
 	/**
 	* Version control for the store's on-disk text, via the reusable `GitRepo`.
 	*
@@ -399,16 +285,16 @@ const KnowledgeConfigSchema = z$1.object({
 	* must not enter the history. Point `root` higher (e.g. at the whole store directory) to share
 	* more, and `ignore` is what keeps the databases out; the defaults already cover them.
 	*/
-	git: z$1.object({
-		mode: z$1.enum(["auto", "off"]).default("auto"),
-		root: z$1.string().default(""),
-		ignore: z$1.array(z$1.string()).default([
+	git: z.object({
+		mode: z.enum(["auto", "off"]).default("auto"),
+		root: z.string().default(""),
+		ignore: z.array(z.string()).default([
 			"*.db",
 			"*.db-wal",
 			"*.db-shm"
 		])
 	}).prefault({}),
-	open: z$1.object({ editor: z$1.string().default("") }).prefault({}),
+	open: z.object({ editor: z.string().default("") }).prefault({}),
 	/**
 	* The knowledge-domain allowlist: the `domain` names a write may use. The default is a small
 	* general set; a deployment narrows or widens it here. An EXPLICIT EMPTY array means no
@@ -416,7 +302,7 @@ const KnowledgeConfigSchema = z$1.object({
 	* allowlist is non-empty additionally accepts every domain already present in its `documents`
 	* table, so renaming the taxonomy never strands existing documents.
 	*/
-	domains: z$1.array(z$1.string()).default([
+	domains: z.array(z.string()).default([
 		"design",
 		"api",
 		"ops",
@@ -431,13 +317,48 @@ const KnowledgeConfigSchema = z$1.object({
 	* rejected — the embedder bounds them and warns once — but their tail would only reach the
 	* FTS leg, so raise this only together with `semantic.max_input_tokens`.
 	*/
-	chunk_size: z$1.number().int().positive().default(500),
+	chunk_size: z.number().int().positive().default(500),
 	/** 10% of `chunk_size`: consecutive chunks share this much context (unchanged ratio). */
-	chunk_overlap: z$1.number().int().nonnegative().default(50),
-	source_priority: z$1.enum(["workspace", "none"]).default("workspace"),
+	chunk_overlap: z.number().int().nonnegative().default(50),
+	source_priority: z.enum(["workspace", "none"]).default("workspace"),
 	ingest: ingestSchema.prefault({})
 });
 //#endregion
+//#region ../contract/lib/family.js
+/**
+* The family root and the two managed directories under it — ONE definition of a convention that
+* four packages would otherwise each spell out.
+*
+* `@avantf/dsh-plugin-base` (the family's environment framework) installs everything it manages under a
+* single root: `$AVANTF_HOME` when set, else `~/.avantf/env`. `tools` holds external binaries
+* (pandoc), `models` the downloaded embedding/rerank weights in the flat layout the transformers.js
+* cache reads. The engine's built-in defaults point HERE, not at the pre-framework
+* `~/.avantf/{tools,models}`: those legacy directories are no longer a fallback anywhere, so a
+* machine that never creates them loses nothing, and no process resolves a path that only works
+* because somebody left a compatibility symlink behind.
+*
+* `provision` mirrors {@link familyHome} (it is deliberately dependency-free, so it cannot import
+* this module); `packages/core/test/family_paths.spec.ts` pins the two copies together so the
+* convention cannot drift.
+*/
+function familyHome$1(env = process.env) {
+	const configured = env["AVANTF_HOME"]?.trim() ?? "";
+	return configured !== "" ? expandTilde(configured) : join(homedir(), ".avantf", "env");
+}
+/** The managed external-binary root (`<family root>/tools`). */
+function familyToolsDir$1(env = process.env) {
+	return join(familyHome$1(env), "tools");
+}
+/** The managed model-cache root (`<family root>/models`). */
+function familyModelsDir(env = process.env) {
+	return join(familyHome$1(env), "models");
+}
+/** `~/x` → `<home>/x`, `~` → `<home>`; anything else is used as given. */
+function expandTilde(path) {
+	if (path === "~") return homedir();
+	return path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+//#endregion
 //#region ../contract/lib/tools.js
 /**
 * The closed value sets these tools accept, exported so no other surface has to retype them.
@@ -447,6 +368,15 @@ const KnowledgeConfigSchema = z$1.object({
 * refusing the new value — with no test failing anywhere. One array, every consumer reading it.
 * (`FACT_STATUSES` lives in `types.ts`, beside the `FactStatus` type it is the single source of.)
 */
+/**
+* The built-in category vocabulary, spelled for the fields that DESCRIBE it.
+*
+* `category` is free-form (`FactCategory` is `… | string`) and stays that way — this is a suggestion
+* a caller can see, not a closed set the engine enforces. It is written once, in `types.ts`, and read
+* here so the constant has a real consumer: before this, nothing at runtime ever read it, which meant
+* editing it changed nothing anywhere.
+*/
+const CATEGORY_HINT = `内置分类：${CATEGORY_VALUES.join(" / ")}；也可自定义。`;
 const CONTRADICTION_RESOLUTIONS = ["true_positive", "false_positive"];
 const QUERY_KINDS = [
 	"all",
@@ -454,6 +384,37 @@ const QUERY_KINDS = [
 	"doc_chunk"
 ];
 /**
+* The longest retrieval query the contract accepts, in characters.
+*
+* There is no useful query beyond this, and there IS a cost: a CJK query is expanded into one trigram
+* OR-phrase per character and evaluated by SQLite **synchronously on the host's event loop** (200 000
+* characters measured at 119 seconds, of which the expansion was 27–52 ms — the rest was `MATCH`). The
+* cap belongs HERE because every entry point derives from this union: the plugin's tools, the MCP
+* inputSchema, the CLI's argv validation and the browser payload are all this same object.
+*/
+const MAX_QUERY_CHARS = 2e3;
+/** Why the cap exists, in the words the caller sees. */
+const QUERY_TOO_LONG = `检索文本最长 ${String(MAX_QUERY_CHARS)} 字符：更长的输入会被展开成成百上千个 OR 短语并在宿主事件循环上同步执行。把范围收窄，或先用 kb_ingest 把整篇文档入库再检索。`;
+/**
+* Vocabulary that describes HOW memory is retained, banned from every model-facing string.
+*
+* The model cannot observe those clocks and has no action to take on them; the one thing such
+* text enables is rewriting a fact to "refresh" it, which defeats the policy it just described.
+* It binds every tool description and parameter description AND the DSH plugin's system-prompt
+* section, because the prompt section is prompt text too and a second copy of the list is a copy
+* that drifts.
+*/
+const RETENTION_VOCABULARY = [
+	"衰减",
+	"消退",
+	"遗忘",
+	"强化",
+	"活跃使用日",
+	"信任度",
+	"永久记忆",
+	"长期有效的信息"
+];
+/**
 * Admin actions that return a FACT VIEW. Their payload goes through
 * {@link modelFacingToolResult}, which drops the retention diagnostics; the other admin
 * actions (`trust_diagnose`, `vectors_diagnose`, …) are diagnostics the caller asked for and
@@ -470,179 +431,179 @@ function modelFacingToolResult(toolKey, action, value) {
 	if (toolKey !== "admin") return value;
 	return FACT_VIEW_ADMIN_ACTIONS.includes(action) ? withoutRetentionDiagnostics(value) : value;
 }
-const RememberUnion = z$1.discriminatedUnion("action", [
-	z$1.object({
-		action: z$1.literal("add"),
-		content: z$1.string().min(1).describe("要写入或替换的事实内容：一句自包含的陈述。action=add 时必填。"),
-		category: z$1.string().optional().describe("分类标签；可选，默认 general。"),
-		ttl_days: z$1.number().int().nonnegative().optional().describe("有效期天数（0 或省略 = 不设有效期；正整数 = 自写入起该天数后自动归档）。update 未给则继承被改写事实的 TTL。")
+const RememberUnion = z.discriminatedUnion("action", [
+	z.object({
+		action: z.literal("add"),
+		content: z.string().min(1).describe("要写入或替换的事实内容：一句自包含的陈述。action=add 时必填。"),
+		category: z.string().optional().describe(`分类标签；可选，默认 general。${CATEGORY_HINT}`),
+		ttl_days: z.number().int().nonnegative().optional().describe("有效期天数（0 或省略 = 不设有效期；正整数 = 自写入起该天数后自动归档）。update 未给则继承被改写事实的 TTL。")
 	}),
-	z$1.object({
-		action: z$1.literal("update"),
-		fact_id: z$1.number().int().positive().describe("要更新的事实 ID。action=update 时必填。"),
-		content: z$1.string().min(1).describe("替换后的新事实内容。action=update 时必填。"),
-		category: z$1.string().optional().describe("新的分类标签；可选，未给则继承被改写事实的分类。"),
-		ttl_days: z$1.number().int().nonnegative().optional().describe("新的有效期天数（0 = 取消有效期）；可选，未给则继承被改写事实的 TTL。")
+	z.object({
+		action: z.literal("update"),
+		fact_id: z.number().int().positive().describe("要更新的事实 ID。action=update 时必填。"),
+		content: z.string().min(1).describe("替换后的新事实内容。action=update 时必填。"),
+		category: z.string().optional().describe(`新的分类标签；可选，未给则继承被改写事实的分类。${CATEGORY_HINT}`),
+		ttl_days: z.number().int().nonnegative().optional().describe("新的有效期天数（0 = 取消有效期）；可选，未给则继承被改写事实的 TTL。")
 	}),
-	z$1.object({
-		action: z$1.literal("remove"),
-		fact_id: z$1.number().int().positive().describe("要删除的事实 ID。action=remove 时必填。"),
-		reason: z$1.string().optional().describe("删除原因；可选。")
+	z.object({
+		action: z.literal("remove"),
+		fact_id: z.number().int().positive().describe("要删除的事实 ID。action=remove 时必填。"),
+		reason: z.string().optional().describe("删除原因；可选。")
 	}),
-	z$1.object({
-		action: z$1.literal("helpful"),
-		fact_id: z$1.number().int().positive().describe("对回答有帮助的事实 ID。action=helpful 时必填。")
+	z.object({
+		action: z.literal("helpful"),
+		fact_id: z.number().int().positive().describe("对回答有帮助的事实 ID。action=helpful 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("unhelpful"),
-		fact_id: z$1.number().int().positive().describe("对回答无帮助的事实 ID。action=unhelpful 时必填。")
+	z.object({
+		action: z.literal("unhelpful"),
+		fact_id: z.number().int().positive().describe("对回答无帮助的事实 ID。action=unhelpful 时必填。")
 	})
 ]);
-const RecallUnion = z$1.discriminatedUnion("action", [
-	z$1.object({
-		action: z$1.literal("search"),
-		query: z$1.string().min(1).describe("检索文本。action=search 时必填。"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。"),
-		max_tokens: z$1.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省用配置 retrieval.max_output_tokens。")
+const RecallUnion = z.discriminatedUnion("action", [
+	z.object({
+		action: z.literal("search"),
+		query: z.string().min(1).max(MAX_QUERY_CHARS, QUERY_TOO_LONG).describe("检索文本。action=search 时必填。"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。"),
+		max_tokens: z.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省用配置 retrieval.max_output_tokens。")
 	}),
-	z$1.object({
-		action: z$1.literal("ask"),
-		subj: z$1.string().optional().describe("三元组主语；action=ask 时与 pred/obj/query 至少给一个。"),
-		pred: z$1.string().optional().describe("三元组谓语。"),
-		obj: z$1.string().optional().describe("三元组宾语。"),
-		query: z$1.string().optional().describe("自然语言问题；给了 query 就按整句检索。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
+	z.object({
+		action: z.literal("ask"),
+		subj: z.string().optional().describe("三元组主语；action=ask 时与 pred/obj/query 至少给一个。"),
+		pred: z.string().optional().describe("三元组谓语。"),
+		obj: z.string().optional().describe("三元组宾语。"),
+		query: z.string().optional().describe("自然语言问题；给了 query 就按整句检索。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
 	}),
-	z$1.object({
-		action: z$1.literal("chain"),
-		subj: z$1.string().min(1).describe("链式推理的起点实体。action=chain 时必填。"),
-		pred: z$1.string().optional().describe("第一跳关系；可选。"),
-		second_pred: z$1.string().optional().describe("第二跳关系；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
+	z.object({
+		action: z.literal("chain"),
+		subj: z.string().min(1).describe("链式推理的起点实体。action=chain 时必填。"),
+		pred: z.string().optional().describe("第一跳关系；可选。"),
+		second_pred: z.string().optional().describe("第二跳关系；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
 	}),
-	z$1.object({
-		action: z$1.literal("probe"),
-		entity: z$1.string().min(1).describe("要探查的实体名。action=probe 时必填。"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。")
+	z.object({
+		action: z.literal("probe"),
+		entity: z.string().min(1).describe("要探查的实体名。action=probe 时必填。"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。")
 	}),
-	z$1.object({
-		action: z$1.literal("reason"),
-		entities: z$1.array(z$1.string().min(1)).min(1).describe("参与推理的实体名数组（≥1）。action=reason 时必填。"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
+	z.object({
+		action: z.literal("reason"),
+		entities: z.array(z.string().min(1)).min(1).describe("参与推理的实体名数组（≥1）。action=reason 时必填。"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
 	}),
-	z$1.object({
-		action: z$1.literal("related"),
-		entity: z$1.string().min(1).describe("要查询相关事实的实体名。action=related 时必填。"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
+	z.object({
+		action: z.literal("related"),
+		entity: z.string().min(1).describe("要查询相关事实的实体名。action=related 时必填。"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选，默认 10。")
 	}),
-	z$1.object({
-		action: z$1.literal("contradict"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		limit: z$1.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。")
+	z.object({
+		action: z.literal("contradict"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		limit: z.number().int().positive().max(50).optional().describe("返回条数上限（1-50）；可选。")
 	})
 ]);
-const AdminUnion = z$1.discriminatedUnion("action", [
-	z$1.object({ action: z$1.literal("stats") }),
-	z$1.object({
-		action: z$1.literal("list"),
-		category: z$1.string().optional().describe("限定分类；可选。"),
-		status: z$1.enum(FACT_STATUSES).optional().describe("按状态过滤；可选，默认 active。"),
-		limit: z$1.number().int().positive().max(500).optional().describe("返回条数上限（1-500）；可选，默认 50。"),
-		offset: z$1.number().int().nonnegative().optional().describe("分页偏移（从 0 开始）；配合 limit 翻页；可选。")
+const AdminUnion = z.discriminatedUnion("action", [
+	z.object({ action: z.literal("stats") }),
+	z.object({
+		action: z.literal("list"),
+		category: z.string().optional().describe("限定分类；可选。"),
+		status: z.enum(FACT_STATUSES).optional().describe("按状态过滤；可选，默认 active。"),
+		limit: z.number().int().positive().max(500).optional().describe("返回条数上限（1-500）；可选，默认 50。"),
+		offset: z.number().int().nonnegative().optional().describe("分页偏移（从 0 开始）；配合 limit 翻页；可选。")
 	}),
-	z$1.object({
-		action: z$1.literal("detail"),
-		fact_id: z$1.number().int().positive().describe("要查看的事实 ID。action=detail 时必填。")
+	z.object({
+		action: z.literal("detail"),
+		fact_id: z.number().int().positive().describe("要查看的事实 ID。action=detail 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("archive"),
-		fact_id: z$1.number().int().positive().describe("要归档的事实 ID。action=archive 时必填。"),
-		reason: z$1.string().optional().describe("归档原因；可选。")
+	z.object({
+		action: z.literal("archive"),
+		fact_id: z.number().int().positive().describe("要归档的事实 ID。action=archive 时必填。"),
+		reason: z.string().optional().describe("归档原因；可选。")
 	}),
-	z$1.object({
-		action: z$1.literal("restore"),
-		fact_id: z$1.number().int().positive().describe("要恢复的事实 ID。action=restore 时必填。")
+	z.object({
+		action: z.literal("restore"),
+		fact_id: z.number().int().positive().describe("要恢复的事实 ID。action=restore 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("pin"),
-		fact_id: z$1.number().int().positive().describe("要标记为长期保留的事实 ID。action=pin 时必填。")
+	z.object({
+		action: z.literal("pin"),
+		fact_id: z.number().int().positive().describe("要标记为长期保留的事实 ID。action=pin 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("unpin"),
-		fact_id: z$1.number().int().positive().describe("要取消长期保留标记的事实 ID。action=unpin 时必填。")
+	z.object({
+		action: z.literal("unpin"),
+		fact_id: z.number().int().positive().describe("要取消长期保留标记的事实 ID。action=unpin 时必填。")
 	}),
-	z$1.object({ action: z$1.literal("trust_diagnose") }),
-	z$1.object({ action: z$1.literal("vectors_diagnose") }),
-	z$1.object({
-		action: z$1.literal("vectors_fix"),
-		dry_run: z$1.boolean().optional().describe("true=只诊断不写入；可选，默认 false。")
+	z.object({ action: z.literal("trust_diagnose") }),
+	z.object({ action: z.literal("vectors_diagnose") }),
+	z.object({
+		action: z.literal("vectors_fix"),
+		dry_run: z.boolean().optional().describe("true=只诊断不写入；可选，默认 false。")
 	}),
-	z$1.object({ action: z$1.literal("contradict_check") }),
-	z$1.object({
-		action: z$1.literal("contradict_resolve"),
-		contradiction_id: z$1.number().int().positive().describe("要裁决的矛盾 ID（来自 `mem_remember` 的 contradictions 或 `mem_recall` 的 contradict）。"),
-		resolution: z$1.enum(CONTRADICTION_RESOLUTIONS).describe("true_positive=确实是矛盾（配 loser_fact_id 归档错的一方）；false_positive=两条并不冲突，关闭该配对且两条都保留。"),
-		loser_fact_id: z$1.number().int().positive().optional().describe("判错的一方（必须是该配对里的两条之一）；给定时会被归档。仅 true_positive 可带。")
+	z.object({ action: z.literal("contradict_check") }),
+	z.object({
+		action: z.literal("contradict_resolve"),
+		contradiction_id: z.number().int().positive().describe("要裁决的矛盾 ID（来自 `mem_remember` 的 contradictions 或 `mem_recall` 的 contradict）。"),
+		resolution: z.enum(CONTRADICTION_RESOLUTIONS).describe("true_positive=确实是矛盾（配 loser_fact_id 归档错的一方）；false_positive=两条并不冲突，关闭该配对且两条都保留。"),
+		loser_fact_id: z.number().int().positive().optional().describe("判错的一方（必须是该配对里的两条之一）；给定时会被归档。仅 true_positive 可带。")
 	}),
-	z$1.object({ action: z$1.literal("maintenance") })
+	z.object({ action: z.literal("maintenance") })
 ]);
 /** The `source` a write gets when it omits one; a document's identity is `(domain, source, title)`. */
 const DEFAULT_KB_SOURCE = "default";
-const KbUnion = z$1.discriminatedUnion("action", [
-	z$1.object({
-		action: z$1.literal("ingest"),
-		text: z$1.string().min(1).optional().describe("要入库的文本；与 source_uri 至少给一个。"),
-		source_uri: z$1.string().optional().describe("来源：本地文件路径或 http(s) URL，内容会被读取后入库；与 text 至少给一个。"),
-		domain: z$1.string().min(1).describe("知识域；取值来自配置 knowledge.domains。action=ingest 时必填。"),
-		source: z$1.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。"),
-		title: z$1.string().optional().describe("文档标题；可选。"),
-		overwrite: z$1.boolean().optional().describe("已确认覆盖同名文档；缺省拒绝。")
+const KbUnion = z.discriminatedUnion("action", [
+	z.object({
+		action: z.literal("ingest"),
+		text: z.string().min(1).optional().describe("要入库的文本；与 source_uri 至少给一个。"),
+		source_uri: z.string().optional().describe("来源：本地文件路径或 http(s) URL，内容会被读取后入库；与 text 至少给一个。"),
+		domain: z.string().min(1).describe("知识域；取值来自配置 knowledge.domains。action=ingest 时必填。"),
+		source: z.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。"),
+		title: z.string().optional().describe("文档标题；可选。"),
+		overwrite: z.boolean().optional().describe("已确认覆盖同名文档；缺省拒绝。")
 	}),
-	z$1.object({
-		action: z$1.literal("import"),
-		paths: z$1.array(z$1.string().min(1)).min(1).describe("要导入的文件路径数组（≥1）。action=import 时必填。"),
-		domain: z$1.string().min(1).describe("知识域；取值来自配置 knowledge.domains。action=import 时必填。"),
-		source: z$1.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。"),
-		overwrite: z$1.boolean().optional().describe("已确认覆盖同名文档；缺省拒绝。")
+	z.object({
+		action: z.literal("import"),
+		paths: z.array(z.string().min(1)).min(1).describe("要导入的文件路径数组（≥1）。action=import 时必填。"),
+		domain: z.string().min(1).describe("知识域；取值来自配置 knowledge.domains。action=import 时必填。"),
+		source: z.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。"),
+		overwrite: z.boolean().optional().describe("已确认覆盖同名文档；缺省拒绝。")
 	}),
-	z$1.object({
-		action: z$1.literal("list"),
-		domain: z$1.string().optional().describe("限定知识域；可选。"),
-		source: z$1.string().optional().describe("限定来源；可选。"),
-		limit: z$1.number().int().positive().optional().describe("本页最多返回多少篇文档（按 updated_at 倒序）；可选，缺省不限。"),
-		offset: z$1.number().int().nonnegative().optional().describe("跳过多少篇（配合 limit 分页）；可选，默认 0。")
+	z.object({
+		action: z.literal("list"),
+		domain: z.string().optional().describe("限定知识域；可选。"),
+		source: z.string().optional().describe("限定来源；可选。"),
+		limit: z.number().int().positive().optional().describe("本页最多返回多少篇文档（按 updated_at 倒序）；可选，缺省不限。"),
+		offset: z.number().int().nonnegative().optional().describe("跳过多少篇（配合 limit 分页）；可选，默认 0。")
 	}),
-	z$1.object({
-		action: z$1.literal("detail"),
-		doc_id: z$1.number().int().positive().describe("文档 ID。action=detail 时必填。")
+	z.object({
+		action: z.literal("detail"),
+		doc_id: z.number().int().positive().describe("文档 ID。action=detail 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("remove"),
-		doc_id: z$1.number().int().positive().describe("要删除的文档 ID。action=remove 时必填。")
+	z.object({
+		action: z.literal("remove"),
+		doc_id: z.number().int().positive().describe("要删除的文档 ID。action=remove 时必填。")
 	}),
-	z$1.object({
-		action: z$1.literal("reindex"),
-		domain: z$1.string().optional().describe("只重建该知识域的索引；可选，缺省全部。"),
-		dry_run: z$1.boolean().optional().describe("true=只报告将重建多少（chunks/实体/向量），不写入；可选，默认 false。")
+	z.object({
+		action: z.literal("reindex"),
+		domain: z.string().optional().describe("只重建该知识域的索引；可选，缺省全部。"),
+		dry_run: z.boolean().optional().describe("true=只报告将重建多少（chunks/实体/向量），不写入；可选，默认 false。")
 	}),
-	z$1.object({
-		action: z$1.literal("sync"),
-		doc_id: z$1.number().int().positive().optional().describe("只同步该文档；可选，缺省检查全部。"),
-		adopt: z$1.boolean().optional().describe("true=认领：把该文档路径上**没有 frontmatter** 的文件重新摄入并补写 frontmatter（action=sync 且给了 doc_id 时才有意义）。整篇覆写会毁掉 frontmatter，此时 `sync` 会**自动**认领（守卫：文件完全没有 frontmatter、正文非空、指纹稳定、路径归属唯一）；不满足守卫的会留在 `unclaimed` 里，用这个参数立即认领。"),
-		dry_run: z$1.boolean().optional().describe("true=只报告哪些文档的受管文件被改过（stale/missing/orphans），不重新摄入；可选，默认 false。")
+	z.object({
+		action: z.literal("sync"),
+		doc_id: z.number().int().positive().optional().describe("只同步该文档；可选，缺省检查全部。"),
+		adopt: z.boolean().optional().describe("true=认领：把该文档路径上**没有 frontmatter** 的文件重新摄入并补写 frontmatter（action=sync 且给了 doc_id 时才有意义）。整篇覆写会毁掉 frontmatter，此时 `sync` 会**自动**认领（守卫：文件完全没有 frontmatter、正文非空、指纹稳定、路径归属唯一）；不满足守卫的会留在 `unclaimed` 里，用这个参数立即认领。"),
+		dry_run: z.boolean().optional().describe("true=只报告哪些文档的受管文件被改过（stale/missing/orphans），不重新摄入；可选，默认 false。")
 	})
 ]);
-const QueryUnion = z$1.object({
-	query: z$1.string().min(1).describe("检索文本，必填。"),
-	kind: z$1.enum(QUERY_KINDS).optional().describe("结果类型：all/fact/doc_chunk；可选，默认 all。"),
-	max_tokens: z$1.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省用配置 retrieval.max_output_tokens。"),
-	domain: z$1.string().optional().describe("限定知识域；可选。"),
-	source: z$1.string().optional().describe("限定来源；可选。"),
-	limit: z$1.number().int().positive().max(50).default(10).describe("返回条数上限（1-50）；可选，默认 10。")
+const QueryUnion = z.object({
+	query: z.string().min(1).max(MAX_QUERY_CHARS, QUERY_TOO_LONG).describe("检索文本，必填。"),
+	kind: z.enum(QUERY_KINDS).optional().describe("结果类型：all/fact/doc_chunk；可选，默认 all。"),
+	max_tokens: z.number().int().nonnegative().optional().describe("本次结果的总 token 上限；0=不限制。缺省用配置 retrieval.max_output_tokens。"),
+	domain: z.string().optional().describe("限定知识域；可选。"),
+	source: z.string().optional().describe("限定来源；可选。"),
+	limit: z.number().int().positive().max(50).default(10).describe("返回条数上限（1-50）；可选，默认 10。")
 });
 const REMEMBER_TOOL = {
 	key: "remember",
@@ -674,9 +635,9 @@ const QUERY_TOOL = {
 	description: "在**用户已入库的文档切片**与记忆事实里做统一检索（跨库）。只检索、不生成答案。",
 	input: QueryUnion
 };
-const KbDomainField = z$1.string().min(1).describe("知识域；取值来自配置 knowledge.domains。");
-const KbSourceField = z$1.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。");
-const KbTitleField = z$1.string().optional().describe("文档标题；可选，缺省取正文首个标题或首行。");
+const KbDomainField = z.string().min(1).describe("知识域；取值来自配置 knowledge.domains。");
+const KbSourceField = z.string().optional().default(DEFAULT_KB_SOURCE).describe("来源名；可选，缺省 default。");
+const KbTitleField = z.string().optional().describe("文档标题；可选，缺省取正文首个标题或首行。");
 const TOOL_SPECS = [
 	REMEMBER_TOOL,
 	RECALL_TOOL,
@@ -685,40 +646,40 @@ const TOOL_SPECS = [
 		key: "kb_add",
 		name: "kb_add",
 		description: "新增一篇文档入库。**只新增、不修改**：同一 `(domain, source, title)` 已存在时会被**拒绝**。给 text 或 source_uri 是单篇（text 是粘贴文本，source_uri 是本地文件路径或 http(s) URL，可摄入文本、PDF、pandoc 能读的文档格式与 .xlsx）；给 paths 是批量导入文件或目录（目录只收 .md/.markdown/.txt/.json/.jsonl/.yaml/.yml/.pdf/.docx/.docm/.odt/.epub/.html/.htm/.xhtml/.tex/.rst/.ipynb/.csv/.tsv/.org/.rtf/.xlsx，不跟随符号链接）。",
-		input: z$1.object({
+		input: z.object({
 			domain: KbDomainField,
 			source: KbSourceField,
 			title: KbTitleField,
-			text: z$1.string().min(1).optional().describe("要入库的文本；与 source_uri、paths 三选一。"),
-			source_uri: z$1.string().optional().describe("来源：本地文件路径或 http(s) URL，内容会被读取后入库。"),
-			paths: z$1.array(z$1.string().min(1)).min(1).optional().describe("批量导入的文件/目录路径（≥1）；给了它就是批量导入。")
+			text: z.string().min(1).optional().describe("要入库的文本；与 source_uri、paths 三选一。"),
+			source_uri: z.string().optional().describe("来源：本地文件路径或 http(s) URL，内容会被读取后入库。"),
+			paths: z.array(z.string().min(1)).min(1).optional().describe("批量导入的文件/目录路径（≥1）；给了它就是批量导入。")
 		})
 	},
 	{
 		key: "kb_list",
 		name: "kb_list",
 		description: "列出知识库里的文档：doc_id、domain、source、title、**受管 .md 文件的绝对路径**与更新时间；给了 doc_id 时只取该篇。",
-		input: z$1.object({
-			doc_id: z$1.number().int().positive().optional().describe("给了 `doc_id` 时只取该篇；可选。"),
-			domain: z$1.string().optional().describe("限定知识域；可选，仅在未给 doc_id 时有意义。"),
-			source: z$1.string().optional().describe("限定来源；可选，仅在未给 doc_id 时有意义。"),
-			limit: z$1.number().int().positive().optional().describe("本页最多返回多少篇（按 updated_at 倒序）；可选，缺省 50。"),
-			offset: z$1.number().int().nonnegative().optional().describe("跳过多少篇（配合 limit 分页）；可选，默认 0。")
+		input: z.object({
+			doc_id: z.number().int().positive().optional().describe("给了 `doc_id` 时只取该篇；可选。"),
+			domain: z.string().optional().describe("限定知识域；可选，仅在未给 doc_id 时有意义。"),
+			source: z.string().optional().describe("限定来源；可选，仅在未给 doc_id 时有意义。"),
+			limit: z.number().int().positive().optional().describe("本页最多返回多少篇（按 updated_at 倒序）；可选，缺省 50。"),
+			offset: z.number().int().nonnegative().optional().describe("跳过多少篇（配合 limit 分页）；可选，默认 0。")
 		})
 	},
 	{
 		key: "kb_remove",
 		name: "kb_remove",
 		description: "删除一篇文档，连同它在 `knowledge.docs.dir` 下的受管 .md 副本。",
-		input: z$1.object({ doc_id: z$1.number().int().positive().describe("要删除的文档 ID。") })
+		input: z.object({ doc_id: z.number().int().positive().describe("要删除的文档 ID。") })
 	},
 	{
 		key: "kb_reindex",
 		name: "kb_reindex",
 		description: "重建知识库索引（分块/实体/向量）。可选限定 domain。",
-		input: z$1.object({
-			domain: z$1.string().optional().describe("只重建该知识域的索引；可选，缺省全部。"),
-			dry_run: z$1.boolean().optional().describe("true=只报告将重建多少，不写入；可选，默认 false。")
+		input: z.object({
+			domain: z.string().optional().describe("只重建该知识域的索引；可选，缺省全部。"),
+			dry_run: z.boolean().optional().describe("true=只报告将重建多少，不写入；可选，默认 false。")
 		})
 	},
 	QUERY_TOOL
@@ -899,8 +860,14 @@ function errorCode(error) {
 * `~/` expansion and boolean env parsing (previously duplicated in core paths,
 * both model adapters, and the config loader).
 */
-/** Expand a leading `~/` against the USER home directory. */
+/** Expand `~/…` (and a BARE `~`) against the USER home directory.
+*
+* The bare form matters: `AVANTF_HOME=~` used to come back verbatim, i.e. as the RELATIVE path `~`,
+* and everything built on it was written into the current working directory. The base kit's own
+* `expandHome` always expanded it, so the two copies disagreed on exactly the input a shell makes
+* easy to type. */
 function expandHome$1(p) {
+	if (p === "~") return homedir();
 	return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
 }
 /** Parse a boolean env var: `0`/`false` → false, unset/empty → undefined, else true. */
@@ -937,21 +904,232 @@ function envAutoDownload() {
 	return project;
 }
 //#endregion
+//#region lib/types/prompt.js
+/**
+* The three system-prompt sections this plugin contributes (DESIGN §10).
+*
+* The TEXTS are user-editable: each section's body lives in its own `.md` under the shared family
+* prompt directory `<data_home>/prompts` (`PROMPT_FILES` maps file → section), and the constants
+* below are both the built-in default and what a missing/blank file is filled with. The identity —
+* section name and order — stays in code, so editing a file cannot silently move a section in the
+* prompt. The loader itself is generic and lives in the family base (`PromptFiles`, exported by
+* `@avantf/dsh-plugin-base`), because "ensure the file exists, otherwise use the default" is the same
+* flow for every section — and taking it from the base at RUNTIME means fixing it takes one base
+* release, not a plugin rebuild. When the base is unavailable the built-in defaults below are used
+* and nothing is written to disk.
+*
+* They exist for something a tool description cannot carry: a description says what a call DOES,
+* never when to reach for it unprompted, and the default behaviour is to wait until asked. So each
+* says only WHEN its store is worth writing or reading. Neither says anything about how memory is
+* retained — that stays out of every model-facing string, held to the contract's
+* `RETENTION_VOCABULARY`, the same list the tool descriptions are held to.
+*
+* The knowledge one is the section whose ABSENCE was measured: a user had just ingested
+* 《Cgroup v2 技术综述》(which answers "cgroup v2 的内存保护" at score 1.0) and asked about it in a
+* session whose prompt named only the memory tools, so the model never looked. A tool description
+* cannot fix that by itself — `kb_query`'s says what the call does and even leads with 记忆 facts,
+* which reads as a memory tool — and the model cannot know the library is relevant to a question
+* without being told to check it. Hence the "先检索一次再作答" nudge, plus the explicit
+* "你看不到库里有什么" clause: the thing that made the miss invisible is that nothing in the
+* prompt acknowledged the store existed at all.
+*
+* `order` 3000/3010 are third-party slots: after the harness's per-tool guidance block (1000–2900)
+* and before its toolset-level guidance (5000). They are not repository-owned placements, so they
+* do not resolve through `getSectionOrder`.
+*
+* The sections say WHAT TO DO and never WHY. The reasoning behind each rule is measured and
+* lives here, in DESIGN §10 and in the CHANGELOG — not in the prompt, where it costs tokens on
+* every step and does not change the action.
+*
+* Kept in its own module — not in `index.ts` — so the text can be read and checked without the
+* plugin entry's `@deepseek-ai/*` runtime imports, which resolve only in a harness workspace.
+*/
+const MEMORY_PROMPT_SECTION = {
+	name: "avantf:memory-usage",
+	order: 3e3,
+	text: "记忆（`mem_remember`）：把**重要且跨会话仍成立**的事实主动记下来——用户偏好、项目决策、环境约束、接口约定、踩过的坑。同一事实的修正用 `update`，一句自包含的陈述。不要记录临时聊天内容、一次性任务的中间状态、能直接从代码或文档读到的内容。"
+};
+/**
+* WHEN to consult the document knowledge base. See the module comment for why this is a separate
+* section rather than a clause inside the memory one: the two stores answer different questions,
+* and a session that needs the knowledge base may have no memory question at all.
+*/
+const KNOWLEDGE_PROMPT_SECTION = {
+	name: "avantf:knowledge-usage",
+	order: 3010,
+	text: "知识库（`kb_query` / `kb_add`）存放**用户提供的成篇资料**：文档、长说明、规范、综述等要按原文查阅的内容。回答涉及已入库资料的问题之前，先用 `kb_query` 检索；命中就按 `source_ref` 引用原文。用户给了值得长期留存的成篇内容就主动 `kb_add` 入库；一句话的事实属于记忆（`mem_remember`），不要入知识库。"
+};
+/**
+* Where each section's text comes from: one `.md` per section, inside the SHARED family prompt
+* directory (`<data_home>/prompts`, see {@link PromptFiles}).
+*
+* Every avantf plugin writes its prompts into that one directory and owns a prefix — `mem-*` here,
+* `work-*` in the work engine — so a deployment can find and diff all of its model-facing text in
+* one place without any plugin having to guess which files belong to it. This manifest is that
+* ownership: a `.md` it does not list is ignored (never read, never written, never deleted).
+*
+* The FILE owns the text; the CODE keeps the identity. Mapping a file name to a section HERE is what
+* makes that true: no edit to the directory can move a section to a different point in the prompt
+* (order) or change the name the harness dedupes on — and no file another plugin owns can be
+* mistaken for one of these.
+*
+* `fallback` is taken from the constant above rather than retyped, so "the text that used to be
+* hardcoded" and "the text a missing file is filled with" cannot drift apart.
+*/
+const PROMPT_FILES = [
+	{
+		file: "mem-memory-usage.md",
+		section: MEMORY_PROMPT_SECTION
+	},
+	{
+		file: "mem-knowledge-usage.md",
+		section: KNOWLEDGE_PROMPT_SECTION
+	},
+	{
+		file: "mem-kb-edit.md",
+		section: {
+			name: "avantf:kb-edit",
+			order: 3020,
+			text: "更新知识库时，要在原文上修改或追加，不要新建一个补充文档。用 `kb_list` 拿到受管 `.md` 的绝对路径，用文件工具修改。在用户明确要求时使用 `kb_remove` 删除。"
+		}
+	}
+];
+/** The generic loader's input: which file, and the body to write/use when it is missing or blank. */
+function promptFileSpecs() {
+	return PROMPT_FILES.map(({ file, section }) => ({
+		file,
+		fallback: section.text
+	}));
+}
+/**
+* Zip the loaded texts back onto their sections, in manifest order.
+*
+* A section whose text is missing from `loaded` (the caller loaded a partial manifest) keeps its
+* built-in default rather than losing its prompt entirely.
+*/
+function buildPromptSections(loaded) {
+	const textByFile = new Map(loaded.map((entry) => [entry.file, entry.text]));
+	return PROMPT_FILES.map(({ file, section }) => ({
+		name: section.name,
+		order: section.order,
+		text: textByFile.get(file) ?? section.text
+	}));
+}
+/** Explanatory phrasings the defaults are forbidden to contain; the spec guards the same shapes. */
+const WHY_WORDS = [
+	"因为",
+	"否则",
+	"原因是",
+	"之所以"
+];
+/**
+* What is worth saying about text the USER wrote — as warnings, never as edits.
+*
+* The defaults are held to hard rules by `prompt_section.spec.ts`: under the budget (they are
+* rendered into every model step), no retention vocabulary, no explanatory "why". An edited file
+* cannot be held to them — it is the user's prompt — but all three are MEASURED regressions rather
+* than style, so a line in the log is cheap and a silently worse prompt is not. Nothing is
+* truncated and nothing is refused: the file is injected exactly as written.
+*/
+function promptTextWarnings(sections) {
+	const out = [];
+	for (const section of sections) {
+		const text = typeof section.text === "string" ? section.text : "";
+		if (text.length >= 400) out.push(`${section.name} is ${String(text.length)} chars (every model step carries it; the built-in default is under ${String(400)})`);
+		for (const word of RETENTION_VOCABULARY) if (text.includes(word)) out.push(`${section.name} describes retention ("${word}"), which invites rewriting a fact to refresh it`);
+		for (const word of WHY_WORDS) if (text.includes(word)) out.push(`${section.name} explains why ("${word}"); the defaults state actions only`);
+	}
+	return out;
+}
+//#endregion
+//#region lib/types/hints.js
+/**
+* The plugin's CONDITIONAL hints: one line per store, contributed only when that store already
+* holds something relevant to what the user just sent (DESIGN §12).
+*
+* These are deliberately NOT part of the always-on usage sections. A usage section says WHEN a
+* store is worth consulting and therefore has to be paid for on every step of every session; this
+* says "there is something here, right now", which is only true sometimes. The two layers compose:
+* the section is the fallback for the paraphrase the lexical probe misses, and the hint is the
+* concrete nudge for the case it catches.
+*
+* ONE LINE PER STORE, never a merged sentence. The two stores answer different questions and
+* either can be the relevant one, so `RelevanceHit` is a closed four-valued answer and each store
+* gets its own contribution — a caller can then see, and later tune or drop, one without the other.
+*
+* WHY EACH LINE NAMES THE PLUGIN. This text is injected as runtime context, and the harness
+* materialises that as a USER-role snapshot in the conversation (`dsh-agent-loop`'s
+* `runtimeContext.project`). Without an author, a line like "记忆里有相关内容" reads as something
+* the user said. The `[avantf-mem 插件]` prefix is what keeps the provenance honest.
+*/
+const MEMORY_HINT = "[avantf-mem 插件] 记忆里有与本次提问相关的事实；需要时用 `mem_recall` 检索。";
+const KNOWLEDGE_HINT = "[avantf-mem 插件] 知识库里有与本次提问相关的内容；需要时用 `kb_query` 检索。";
+/**
+* Map one answer to the two contributions, as text.
+*
+* An empty string is the "contribute nothing" value: `renderPrompt`/`renderContextSections` drop
+* empty text, so `none` (and the missing half of `memory`/`knowledge`) costs no tokens at all.
+*/
+function hintLines(hit) {
+	return {
+		memory: hit === "memory" || hit === "both" ? MEMORY_HINT : "",
+		knowledge: hit === "knowledge" || hit === "both" ? KNOWLEDGE_HINT : ""
+	};
+}
+/**
+* The plain text of an inbox message, or `''` when it carries none.
+*
+* `dsh-agent-loop`'s own extractor returns `undefined` unless the message is exactly ONE text
+* block; a steered or multi-part message would then silently produce no hint. Concatenating the
+* text blocks keeps the probe working for those, and non-text blocks (images) are simply skipped —
+* the probe is lexical, so it has nothing to say about them anyway.
+*/
+function messageText(message) {
+	const content = message?.content;
+	if (!Array.isArray(content)) return "";
+	return content.map((block) => {
+		const b = block;
+		return b?.type === "text" && typeof b.text === "string" ? b.text : "";
+	}).filter(Boolean).join("\n");
+}
+//#endregion
 //#region ../core/lib/config/paths.js
 /**
 * Resolve the data home (default `~/.avantf`).
 *
-* Precedence, per DESIGN §3: an EXPLICIT caller value (layer ⑤) → `AVANTF_HOME`
-* (layer ④) → the configured/default `dataHome`. `common.dataHome` cannot stand in
-* for layer ⑤: the schema gives it a default, so it always holds a value and would
-* make an explicit argument indistinguishable from "nothing was configured" —
-* which is exactly how the env var used to win over a caller's own `dataHome`.
+* Precedence, per DESIGN §3 and the family layering (root `AGENTS.md` 「边界与路径」: built-in →
+* profile → store → ENV → explicit): an EXPLICIT caller value (⑤) → `AVANTF_HOME` (④) → the
+* configured `common.dataHome` (②) → `~/.avantf`. The environment is a deployment override and
+* outranks the config file.
+*
+* `configured` cannot stand in for layer ⑤: the schema gives it a default, so it always holds a
+* value and would make an explicit argument indistinguishable from "nothing was configured" — which
+* is exactly how the env var used to win over a caller's own `dataHome`.
+*
+* The slots are NAMED for the same reason the base kit's copy is: the two implementations used to
+* disagree about their POSITIONAL order (`(explicit, env, common)` here, `(common, explicit)`…
+* whichever way a reader guessed), so "which slot does the profile's `dataHome` belong in?" was
+* answerable only by reading the call site. The base kit implements the same rule with the same named
+* shape, and `packages/plugin/test/family_pin.spec.ts` pins the two implementations together.
+*/
+function resolveDataHome(input) {
+	const layer5 = input.explicit?.trim() ?? "";
+	const fromEnv = process.env["AVANTF_HOME"]?.trim() ?? "";
+	const layer2 = input.common.dataHome?.trim() ?? "";
+	return expandHome$1(layer5 !== "" ? layer5 : fromEnv !== "" ? fromEnv : layer2 !== "" ? layer2 : "~/.avantf");
+}
+/**
+* Every config file lives in ONE directory, beside the prompt files.
+*
+* The layering is unchanged (① built-in → ② common → ③ store → ④ env → ⑤ explicit); only the
+* locations moved, so all of a deployment's editable text — `configs/*.yaml` and `prompts/*.md` —
+* is in one place instead of scattered through `memory/` and `knowledge/` next to the databases.
 */
-function resolveDataHome(common, explicit) {
-	return expandHome$1(explicit || process.env["AVANTF_HOME"] || common.dataHome || "~/.avantf");
+function configsDir(home) {
+	return join(home, "configs");
 }
 function commonConfigPath(home) {
-	return join(home, "config.yaml");
+	return join(configsDir(home), "common.yaml");
 }
 function memoryDir(home) {
 	return join(home, "memory");
@@ -960,10 +1138,10 @@ function knowledgeDir(home) {
 	return join(home, "knowledge");
 }
 function memoryConfigPath(home) {
-	return join(memoryDir(home), "config.yaml");
+	return join(configsDir(home), "memory.yaml");
 }
 function knowledgeConfigPath(home) {
-	return join(knowledgeDir(home), "config.yaml");
+	return join(configsDir(home), "knowledge.yaml");
 }
 function memoryDbPath(home, override) {
 	const fromEnv = process.env["AVANTF_MEM_DB"];
@@ -988,6 +1166,97 @@ function knowledgeDocsDir(home, override) {
 function ensureDataLayout(home) {
 	mkdirSync(memoryDir(home), { recursive: true });
 	mkdirSync(knowledgeDir(home), { recursive: true });
+	mkdirSync(configsDir(home), { recursive: true });
+}
+//#endregion
+//#region ../core/lib/config/config_files.js
+/**
+* The default `configs/common.yaml`, written when the file is missing or blank.
+*
+* It is **comments only**, on purpose: the built-in defaults are already in force, so an all-comment
+* file changes NOTHING about how the engine behaves — it only puts the knobs, their defaults and the
+* two managed keys' escape hatches where a reader will find them. Uncommenting a line is the edit;
+* deleting the file brings the defaults straight back.
+*
+* The rule mirrors the prompt files (the plugins' `src/prompt_files.ts`): missing or blank is an
+* unfinished edit, not an empty configuration, so it is filled in. A file with ANY content is the
+* user's and is never rewritten.
+*
+* Keys must match the schema in `@avantf/mem-contract` (`ConfigSchema`): an unknown key in an
+* UNCOMMENTED line is warned about by the loader, so a wrong name here would be a trap rather than a
+* hint. `config_files.spec.ts` pins the ones this template names.
+*/
+const DEFAULT_COMMON_CONFIG = `# avantf-mem 公共配置（分层第②层）。这里全是注释：删掉/留空 = 用内建默认，取消注释即生效。
+# 分层（低→高）：① 内建默认 → ② 本文件 → ③ 同目录的 memory.yaml / knowledge.yaml（缺失=不覆盖）
+#               → ④ 环境变量 → ⑤ 插件/CLI 显式传参
+# 所有可编辑文本都在 ~/.avantf 下：configs/*.yaml（本目录）与 prompts/*.md（模型提示词）。
+
+# 数据根不在这里配：它由 ④ AVANTF_HOME（或 CLI --data-home、插件 profile 的 dataHome）决定 ——
+# 本文件就在数据根里面，解析根的时候还没读到它，所以写在这里的 dataHome 对数据根无效（DESIGN §3）。
+
+# semantic:                           # 嵌入后端（记忆与知识共用，跨库分数才可比）
+#   backend: local_bge
+#   local_model: Xenova/bge-small-zh-v1.5   # 必须是 ONNX 仓库
+#   dim: 512
+#   auto_download: true
+#   ⚠️ cache_dir / mirror 由家族底座 @avantf/dsh-plugin-base 管理：写在这里会被忽略并告警。
+#      缓存目录用环境变量 AVANTF_MEM_MODEL_CACHE，镜像用 AVANTF_MEM_MODEL_MIRROR（或 HF_ENDPOINT）。
+
+# rerank:                             # 重排的唯一开关；none = 不加载任何重排模型
+#   backend: none
+#   local_model: Xenova/bge-reranker-base
+
+# vectorStore:
+#   backend: auto                     # auto = 越过阈值自动从 local_numpy 迁到 hnswlib
+#   auto_thresholds:
+#     hnswlib: 2000
+#   hnswlib_ef_search: 256            # ANN 的召回/速度旋钮，语料变大先调它
+
+# retriever:                          # 三条检索腿在融合里的权重
+#   weight_semantic: 0.55
+#   weight_fts: 0.30
+#   weight_jaccard: 0.15
+
+# lifecycle:
+#   purge_after_archived_days: 365    # 归档事实的物理清理窗口（活跃日）
+#   contradiction_threshold: 0.6
+
+# trust:
+#   decay_per_day: 0.0055…
+#   presence:
+#     heartbeat_minutes: 60           # 常驻进程的心跳（活跃日时钟与生命周期扫描）
+
+# tools:                              # 外部二进制（pandoc）的受管目录
+#   dir: ''                           # 留空 = 家族根 tools（~/.avantf/env/tools）；AVANTF_TOOLS_DIR 可覆盖
+#   auto_install: true
+`;
+/**
+* Ensure the common config exists with content, and hand back the path either way.
+*
+* Never throws: an unwritable data home must not keep the engine (or the plugin mount) from working
+* — the built-in defaults are always available, and a missing file is the same thing to the loader
+* as an empty one.
+*/
+function ensureCommonConfigFile(path, logger) {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		if (existsSync(path)) {
+			if (readFileSync(path, "utf8").replace(/^\uFEFF/u, "").trim() !== "") return;
+			writeAtomic(path, DEFAULT_COMMON_CONFIG);
+			logger?.info(`config file was blank and has been filled with the default: ${path}`);
+			return;
+		}
+		writeAtomic(path, DEFAULT_COMMON_CONFIG);
+		logger?.info(`config file created with the default (all comments): ${path}`);
+	} catch (error) {
+		logger?.warn(`config file ${path} is unusable (${error instanceof Error ? error.message : String(error)}); using the built-in defaults`);
+	}
+}
+/** Temp file + rename, the same shape the managed document copy and the store config use. */
+function writeAtomic(path, text) {
+	const tmp = `${path}.tmp-${String(process.pid)}`;
+	writeFileSync(tmp, text, "utf8");
+	renameSync(tmp, path);
 }
 //#endregion
 //#region ../core/lib/config/loader.js
@@ -1163,13 +1432,27 @@ function applyEnvLayer(common) {
 	return next;
 }
 /**
-* Load config with layering: ① built-in defaults → ② `~/.avantf/config.yaml`
+* Load config with layering: ① built-in defaults → ② `~/.avantf/configs/common.yaml`
 * (common) → ③ `~/.avantf/{memory,knowledge}/config.yaml` (store) → ④ env →
 * ⑤ explicit. Returns the resolved per-store config + data home.
 */
 function loadConfig(opts) {
 	const logger = opts?.logger ?? defaultLogger;
-	let common = { ...defaultConfig };
+	let common = {
+		...defaultConfig,
+		tools: {
+			...defaultConfig.tools,
+			dir: defaultConfig.tools.dir === "" ? familyToolsDir$1() : defaultConfig.tools.dir
+		},
+		semantic: {
+			...defaultConfig.semantic,
+			cache_dir: defaultConfig.semantic.cache_dir === "" ? familyModelsDir() : defaultConfig.semantic.cache_dir
+		},
+		rerank: {
+			...defaultConfig.rerank,
+			cache_dir: defaultConfig.rerank.cache_dir === "" ? familyModelsDir() : defaultConfig.rerank.cache_dir
+		}
+	};
 	const managed = opts?.managedRoots;
 	if (managed !== void 0) common = {
 		...common,
@@ -1190,8 +1473,12 @@ function loadConfig(opts) {
 		...common,
 		dataHome: opts.dataHome
 	});
-	const home = resolveDataHome(common, opts?.dataHome);
+	const home = resolveDataHome({
+		common,
+		explicit: opts?.dataHome
+	});
 	ensureDataLayout(home);
+	ensureCommonConfigFile(commonConfigPath(home), logger);
 	const commonYaml = readYamlOrNull(commonConfigPath(home));
 	if (commonYaml) {
 		stripManagedModelKeys(commonYaml, commonConfigPath(home), logger);
@@ -1236,7 +1523,7 @@ function loadConfig(opts) {
 }
 /** The built-in `tools` section (layer ①); the config schema defaults to exactly this shape. */
 const DEFAULT_TOOLS_CONFIG = {
-	dir: "~/.avantf/tools",
+	dir: "",
 	mirror: [
 		"https://ghfast.top/{url}",
 		"https://ghproxy.net/{url}",
@@ -1251,8 +1538,24 @@ const DEFAULT_TOOLS_CONFIG = {
 * tool already here?" before any runtime has installed its settings — which is what keeps a startup
 * sweep from re-downloading a tool that is already on disk.
 */
-function defaultToolsDir() {
-	return expandHome(DEFAULT_TOOLS_CONFIG.dir);
+function defaultToolsDir(env = process.env) {
+	return familyToolsDir(env);
+}
+/**
+* The family root and its managed directories — `$AVANTF_HOME` when set, else `~/.avantf/env`.
+*
+* Mirrored from `@avantf/mem-contract`'s `familyHome()` / `familyToolsDir()`: this package is
+* deliberately dependency-free (node builtins only), so it cannot import them, and
+* `packages/core/test/family_paths.spec.ts` pins the two copies together so the convention cannot
+* drift. `@avantf/dsh-plugin-base` installs everything it manages under this one root.
+*/
+function familyHome(env = process.env) {
+	const configured = env["AVANTF_HOME"];
+	return configured !== void 0 && configured.trim() !== "" ? expandHome(configured.trim()) : join(homedir(), ".avantf", "env");
+}
+/** The managed external-binary root (`<family root>/tools`). */
+function familyToolsDir(env = process.env) {
+	return join(familyHome(env), "tools");
 }
 /**
 * The project-wide download kill switch (`AVANTF_MEM_AUTO_DOWNLOAD=0`), the same variable the model
@@ -1294,7 +1597,7 @@ function resolveToolsDir(config, env = process.env) {
 	const fromEnv = env["AVANTF_TOOLS_DIR"];
 	if (fromEnv !== void 0 && fromEnv !== "") return expandHome(fromEnv);
 	if (config.dir !== "") return expandHome(config.dir);
-	return expandHome(DEFAULT_TOOLS_CONFIG.dir);
+	return defaultToolsDir(env);
 }
 /**
 * Read the `tools` section out of an UNVALIDATED config object (the value comes from YAML, so every
@@ -1624,21 +1927,43 @@ async function extractArchive(pack, archive, destination, artifact) {
 * Atomically publish a fully-built directory as the artifact's version directory.
 *
 * `renameSync` inside one filesystem is atomic, so a reader (another process, or the next `ensure`)
-* sees either the old state or the complete new one — never a half-written tool. A pre-existing
-* target is REPLACED: a retry after a failed verification must not be blocked by the wreckage of the
-* previous attempt.
+* sees either the old tree or the complete new one — never a half-written tool. A pre-existing target
+* is REPLACED, and it is moved ASIDE rather than deleted first: `rm -rf` on a real tool tree runs for
+* hundreds of milliseconds, and for that whole window the version directory did not exist, so a
+* concurrently started pandoc got ENOENT and retried the install. Two renames shorten that window to
+* microseconds, and if the second one fails the old tree is moved back — a failed publish leaves the
+* previous install in place instead of nothing.
+*
+* What this does NOT claim: there is no cross-process LOCK. Two processes can install the same
+* version at once and both pay for the download and the extract; the second publish wins (each
+* staging tree is complete, so the result is a complete `bin/<binary>` either way). A lock would have
+* to detect its own stale holders and would have to tell the waiter when the winner is done, which is
+* a coordination protocol rather than a rename — out of scope here, and recorded instead of implied.
+*
+* A crash between the two renames leaves the old tree under `<target>.old-<pid>-<rand>` beside the
+* version directory. Nothing enumerates that parent, so the residue is inert; the next install of the
+* same version replaces the target normally.
 */
 function publishAtomically(staging, target, artifact) {
 	mkdirSync(dirname(target), { recursive: true });
-	rmSync(target, {
-		recursive: true,
-		force: true
-	});
+	const moved = existsSync(target) ? `${target}.old-${String(process.pid)}-${Math.random().toString(36).slice(2, 8)}` : null;
+	if (moved !== null) try {
+		renameSync(target, moved);
+	} catch (error) {
+		throw new ProvisionError("extract", artifact, `替换旧版本失败（${target} → ${moved}）：${describeError$1(error)}`);
+	}
 	try {
 		renameSync(staging, target);
 	} catch (error) {
+		if (moved !== null) try {
+			renameSync(moved, target);
+		} catch {}
 		throw new ProvisionError("extract", artifact, `原子落盘失败（${staging} → ${target}）：${describeError$1(error)}`);
 	}
+	if (moved !== null) rmSync(moved, {
+		recursive: true,
+		force: true
+	});
 }
 function makeScratch(toolsDir, id) {
 	const base = `${toolsDir}/.tmp`;
@@ -2763,16 +3088,18 @@ async function parseQueryPattern(query) {
 //#endregion
 //#region ../core/lib/modelBootstrap.js
 /**
-* This module does NOT import the family base `@avantf/dsh-compat` — and nothing else does either.
+* This module does NOT import the family base `@avantf/dsh-plugin-base` — and nothing else in the
+* engine does either.
 *
-* `@avantf/mem` is inlined into the plugin bundle, and the base is a *devDependency of the plugin*
-* (the source of the declared range only): the family framework `@avantf/dsh-envinit` fetches it
-* into its managed root at startup and the plugin loads THAT copy by file URL
-* (`plugin/src/envinit.ts`). A static import here would therefore put a top-level
-* `import "@avantf/dsh-compat"` in the artifact that resolves nowhere — the artifact would throw
-* `ERR_MODULE_NOT_FOUND` during module evaluation, before any of our code ran. The plugin computes
-* the verdict itself (from the framework-provided base) and hands it over as PLAIN DATA; this
-* module only reads it (see AGENTS.md, «The `@avantf/*` family dependency is provisioned»).
+* `@avantf/mem` is inlined into the plugin bundle, and the base is a **peer of the plugin** (plus a
+* `devDependency` that is only the source of the declared range): the plugin's inlined zero-dependency
+* bootstrap resolves the installed base at startup and loads it by file URL (`plugin/src/envinit.ts`).
+* A static import here would therefore put a top-level `import "@avantf/dsh-plugin-base"` in the
+* artifact that may resolve nowhere — the artifact would throw `ERR_MODULE_NOT_FOUND` during module
+* evaluation, before any of our code ran, which is exactly the failure the family forbids ("the base
+* missing must degrade the plugin, never prevent it from loading"). The plugin computes the verdict
+* itself (off the runtime-loaded base) and hands it over as PLAIN DATA; this module only reads it
+* (see AGENTS.md, «The three family hard constraints»).
 */
 const COMPAT_PREFIX = "compat:";
 /** Hard cap on the host-readiness wait (see {@link WarmOptions.waitForCapMs}). */
@@ -2945,7 +3272,7 @@ function runtimeOf(artifactEnv) {
 * It used to be a parallel `warmModelsAsync(...)` call beside the tools sweep, which meant two
 * startup mechanisms with two logging vocabularies and no single place that answered "is this host
 * fully provisioned?". The model has no pinned version and no managed directory of its own ON THIS
-* LEGACY PATH (the transformers.js cache under the legacy `~/.avantf/models` is the layout), so it
+* (the flat `<repo>/<file>` layout the transformers.js cache reads), so it
 * declares neither; its `isPresent` is `false` because "is the model warm?" is not a question that
 * can be answered without attempting the warm-up, and the warm-up is cheap when the cache is
 * already there (measured ~1.2 s, in the background). The DSH plugin uses this sweep only when the
@@ -3521,7 +3848,7 @@ var LocalBgeBackend = class {
 		this.pipeFactory = pipeFactory;
 		this.env = {
 			mirror: process.env["AVANTF_MEM_MODEL_MIRROR"] ?? process.env["HF_ENDPOINT"] ?? env?.mirror ?? "https://hf-mirror.com",
-			cacheDir: process.env["AVANTF_MEM_MODEL_CACHE"] ?? env?.cacheDir ?? "~/.avantf/models",
+			cacheDir: process.env["AVANTF_MEM_MODEL_CACHE"] ?? blankToFamilyModels$1(env?.cacheDir),
 			autoDownload: envAutoDownload() ?? env?.autoDownload ?? true
 		};
 		this.gate = new WarmGate(() => this.env.autoDownload);
@@ -3696,6 +4023,10 @@ function applyModelEnv(mod, env) {
 	mod.env.allowRemoteModels = env.autoDownload;
 	mod.env.allowLocalModels = true;
 }
+/** A blank `cache_dir` means "not configured": the family root's `models`, never the pre-framework path. */
+function blankToFamilyModels$1(configured) {
+	return configured !== void 0 && configured.trim() !== "" ? configured : familyModelsDir();
+}
 //#endregion
 //#region ../retrieval-core/lib/adapters/local_reranker.js
 /** Rerank pairs are classified in batches to bound peak memory. */
@@ -3735,7 +4066,7 @@ var LocalReranker = class {
 		this.pipeFactory = pipeFactory;
 		this.env = {
 			mirror: process.env["AVANTF_MEM_MODEL_MIRROR"] ?? process.env["HF_ENDPOINT"] ?? env?.mirror ?? "https://hf-mirror.com",
-			cacheDir: process.env["AVANTF_MEM_MODEL_CACHE"] ?? env?.cacheDir ?? "~/.avantf/models",
+			cacheDir: process.env["AVANTF_MEM_MODEL_CACHE"] ?? blankToFamilyModels(env?.cacheDir),
 			autoDownload: envAutoDownload() ?? env?.autoDownload ?? true
 		};
 		this.gate = new WarmGate(() => this.env.autoDownload);
@@ -3831,6 +4162,10 @@ async function createClassifier(model, env) {
 	applyModelEnv(mod, env);
 	return await mod.pipeline("text-classification", model);
 }
+/** A blank `cache_dir` means "not configured": the family root's `models`, never the pre-framework path. */
+function blankToFamilyModels(configured) {
+	return configured !== void 0 && configured.trim() !== "" ? configured : familyModelsDir();
+}
 //#endregion
 //#region ../retrieval-core/lib/adapters/local_numpy.js
 /**
@@ -4764,7 +5099,7 @@ const PLAIN_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
 * Resolving the pandoc binary for the converter.
 *
 * The binary is NOT this package's business to install — `@avantf/mem-provision` owns that, the
-* pinned version, the mirror list, and the `~/.avantf/tools` layout. What this module adds is the
+* pinned version, the mirror list, and the managed-tools layout. What this module adds is the
 * converter's view of it: one place that knows how to ask for the executable, where an explicit
 * override goes, and why a missing pandoc is a hard failure rather than a fallback.
 *
@@ -4796,7 +5131,7 @@ function setPandocProvisioning(settings) {
 /** The current settings, defaulting to the managed directory + the package's mirror defaults. */
 function pandocProvisioning() {
 	return provisioning ?? {
-		toolsDir: join(homedir(), ".avantf", "tools"),
+		toolsDir: defaultToolsDir(),
 		mirror: [],
 		autoInstall: true
 	};
@@ -5712,7 +6047,7 @@ function buildFtsQuery(query, tokenizer = resolveFtsTokenizer()) {
 		} else if (clean.length >= 2) parts.push(`"${clean}"`);
 	}
 	if (!parts.length) return null;
-	return parts.join(" OR ");
+	return [...new Set(parts)].slice(0, 64).join(" OR ");
 }
 //#endregion
 //#region ../core/lib/db/conn.js
@@ -6793,12 +7128,20 @@ var FactsDao = class FactsDao {
 	linkSupersede(factId, supersedesId) {
 		this.db.prepare("UPDATE facts SET supersedes_id = ? WHERE fact_id = ? AND supersedes_id IS NULL").run(supersedesId, factId);
 	}
-	/** Restore an archived fact, settling its trust and refreshing the idle clock (spec §2.6). */
+	/**
+	* Restore an archived fact, settling its trust and refreshing the idle clock (spec §2.6).
+	*
+	* `AND status = 'archived'` is load-bearing, like the guard on every sibling above: this UPDATE
+	* clears the archive bookkeeping and refreshes `last_retrieved_at`, so ungated it would take an
+	* ACTIVE row and (a) push its idle clock forward — silently extending the life of a fact the next
+	* tick was about to re-archive — and (b) reset `trust_score` to the settled value it computed. It
+	* returned `1` either way, so the caller could not tell that a row it never asked about had moved.
+	*/
 	restore(factId, trust, clock) {
 		return this.db.prepare(`UPDATE facts
             SET status = 'active', archived_at = NULL, archive_reason = NULL, archived_clock = NULL,
                 trust_score = ?, settle_clock = ?, last_retrieved_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP
-          WHERE fact_id = ?`).run(trust, clock, factId).changes;
+          WHERE fact_id = ? AND status = 'archived'`).run(trust, clock, factId).changes;
 	}
 	bumpHelpful(factId, delta) {
 		this.db.prepare("UPDATE facts SET helpful_count = MAX(0, helpful_count + ?) WHERE fact_id = ?").run(delta, factId);
@@ -8416,7 +8759,7 @@ var MemoryStore = class {
 		if (rows.length === 0) return {
 			logged: [],
 			checked: 0,
-			pending: 0
+			pending: this.facts.countPendingConflicts()
 		};
 		this.conflictDrainCursor = rows[rows.length - 1].fact_id;
 		const checked = this.contradictions.checkMany(rows.map((r) => r.fact_id));
@@ -9397,6 +9740,20 @@ var ChunksDao = class {
 		this.db.prepare("UPDATE doc_chunks SET semantic_vector = ?, embedding_model = ? WHERE chunk_id = ?").run(bytes, embeddingModel, chunkId);
 	}
 	/**
+	* The doc's chunks WITH their stored vectors — the reuse index for a re-ingest.
+	*
+	* A re-ingest deletes and re-inserts every chunk (new ids), so without this the only way to keep a
+	* vector is to re-encode the same text; `vectorReusable` already knows how to tell "unchanged", but
+	* only `reindex` could use it. Read BEFORE the replace, inside its transaction.
+	*/
+	vectorStateForDoc(docId) {
+		return this.db.prepare(`SELECT dc.chunk_id AS chunk_id, dc.text AS text, dc.content_hash AS content_hash,
+                dc.embedding_model AS embedding_model, dc.entities_version AS entities_version,
+                (dc.semantic_vector IS NOT NULL) AS has_vector, dc.semantic_vector AS vec
+           FROM doc_chunks dc
+          WHERE dc.doc_id = ?`).all(docId);
+	}
+	/**
 	* Write a batch of vectors in ONE transaction.
 	*
 	* `setVector` is autocommit: each chunk costs a commit (measured 14.2 µs/row against 2.2 µs in a
@@ -9507,8 +9864,11 @@ var ChunksDao = class {
 	* Entity-overlap candidates, most-shared first and CAPPED (see the memory store's sibling).
 	*
 	* `limit` is applied per name-batch and the batches are unioned, so the result is bounded by
-	* `limit x ceil(names/batch)` — still corpus-independent, which is the property that matters:
-	* the caller only ever keeps `overFetch` entries after fusion.
+	* `limit x ceil(names/batch)` — corpus-independent, which is what this query can promise. The
+	* caller is expected to enforce the real `cap` on the union AFTER scoring it (it re-computes the
+	* true Jaccard in JS): a union of per-batch tops is not a top-N, and a leg that returns more than
+	* the cap makes `scores.size === legCap` — the "was this leg trimmed" signal — report the opposite
+	* of the truth. (The memory store's sibling does not batch, so its single `LIMIT` is already exact.)
 	*/
 	candidatesByEntityNames(names, domain, source, limit) {
 		if (limit <= 0) return [];
@@ -9983,10 +10343,10 @@ async function documentText(bytes, label) {
 /**
 * Where these knobs live. The boundary belongs to the knowledge store (only it
 * ingests), so it sits in the per-store config — naming it in the errors matters,
-* because the obvious place to look is the common `~/.avantf/config.yaml`, where
+* because the obvious place to look is the common `~/.avantf/configs/common.yaml`, where
 * the `knowledge.` prefix is a key the loader will reject as unknown.
 */
-const KB_CONFIG_FILE = "~/.avantf/knowledge/config.yaml";
+const KB_CONFIG_FILE = "~/.avantf/configs/knowledge.yaml";
 /** Strip IPv6 brackets and the FQDN root dot — `localhost.` and `[::1]` are `localhost` and `::1`. */
 function normalizeHost(hostname) {
 	return (hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname).toLowerCase().replace(/\.$/, "");
@@ -10230,6 +10590,11 @@ function describePaths(paths) {
 		files: paths.length
 	};
 }
+/**
+* The listing shape is the contract's {@link BrowseListing} (re-exported above for this package's
+* callers). The engine fills it in and the host Remote method declares that same interface as its
+* payload, so the shape has exactly one definition and one check.
+*/
 function insideRoots(path, roots, allowAnywhere) {
 	if (allowAnywhere) return true;
 	return roots.some((root) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep));
@@ -10685,7 +11050,7 @@ var GitRepo = class {
 //#region ../core/lib/config/domains.js
 /**
 * Append one 知识域 to the STORE config's top-level `domains` allowlist
-* (`~/.avantf/knowledge/config.yaml`, layer ③ of `loader.ts`) and return the new list.
+* (`~/.avantf/configs/knowledge.yaml`, layer ③ of `loader.ts`) and return the new list.
 *
 * This is the write half of the UI-only `kbAddDomain` path, so the user adds a domain once in the
 * 知识 tab instead of hand-editing YAML. It writes to the STORE config rather than the common one:
@@ -11150,6 +11515,7 @@ var KnowledgeStore = class {
 		const result = this.db.transaction(() => {
 			const docId = this.docs.upsert(domain, source, docTitle, sourceUri);
 			const oldChunkIds = this.chunks.idsForDoc(docId);
+			const reusable = this.reusableByHash(docId, this.vectorSpace());
 			this.chunks.deleteForDoc(docId);
 			this.docs.touch(docId, sourceUri);
 			return {
@@ -11162,11 +11528,12 @@ var KnowledgeStore = class {
 					sourceRef: `${domain}:${source}:${docId}:${idx}`,
 					charStart: chunk.start,
 					charEnd: chunk.end
-				})))
+				}))),
+				reusable
 			};
 		})();
 		this.evictVectors(result.oldChunkIds);
-		const indexed = await this.indexChunks(result.newChunkIds);
+		const indexed = await this.indexChunks(result.newChunkIds, result.reusable);
 		return {
 			doc_id: result.doc_id,
 			chunks: chunks.length,
@@ -11246,22 +11613,88 @@ var KnowledgeStore = class {
 	* Extract entities per chunk (persisted) and encode/persist chunk vectors.
 	*
 	* Returns how many chunks did NOT get a vector, so the caller can put it in the tool result. A
-	* missing model counts every chunk: the document is still searchable by text and entity, but not
-	* semantically, and "入库成功 N 段" must not imply otherwise.
+	* missing model counts every chunk that had no reusable vector: the document is still searchable by
+	* text and entity, but not semantically, and "入库成功 N 段" must not imply otherwise.
 	*/
-	async indexChunks(chunkIds) {
+	async indexChunks(chunkIds, reusable) {
 		if (!chunkIds.length) return { vectors_failed: 0 };
 		const rows = this.chunks.texts(chunkIds);
 		await this.replaceChunkEntities(rows);
 		this.chunks.setEntitiesVersion(rows.map((r) => r.chunk_id), 1);
+		const space = this.vectorSpace();
+		const { remaining } = this.writeReusedVectors(rows, space, reusable);
 		if (!this.semantic.isAvailable()) {
 			this.semantic.ensureWarm?.();
-			return { vectors_failed: rows.length };
+			return { vectors_failed: remaining.length };
 		}
-		const { failed } = await this.encodeAndStore(rows, this.vectorSpace());
+		const { failed } = await this.encodeAndStore(remaining, space);
 		return { vectors_failed: failed };
 	}
 	/**
+	* The doc's stored vectors that still APPLY, keyed by content hash (see {@link vectorReusable}).
+	*
+	* Called inside the ingest transaction, before the replace: two chunks with the same text are one
+	* hash, and the first row wins — the reuse is only a cache lookup, so a duplicate entry cannot be
+	* distinguished from a hit and need not be.
+	*/
+	reusableByHash(docId, space) {
+		const out = /* @__PURE__ */ new Map();
+		for (const row of this.chunks.vectorStateForDoc(docId)) {
+			if (row.vec === null || row.content_hash === null) continue;
+			if (!this.vectorReusable(row, space)) continue;
+			if (!out.has(row.content_hash)) out.set(row.content_hash, row.vec);
+		}
+		return out;
+	}
+	/**
+	* Write back the vectors a re-ingest can reuse, and report which rows still need the model.
+	*
+	* A row is only reused when the lookup misses nothing: any row whose write fails, or whose text has
+	* no reusable vector, comes back in `remaining` and is encoded as before — so the reuse path cannot
+	* leave a chunk unindexed that the plain path would have indexed.
+	*/
+	writeReusedVectors(rows, space, reusable) {
+		if (reusable === void 0 || reusable.size === 0) return {
+			reused: 0,
+			remaining: [...rows]
+		};
+		const remaining = [];
+		const writes = [];
+		for (const r of rows) {
+			const bytes = reusable.get(contentHash(r.text));
+			if (bytes === void 0) remaining.push(r);
+			else writes.push({
+				chunk_id: r.chunk_id,
+				bytes,
+				embeddingModel: space,
+				text: r.text
+			});
+		}
+		if (writes.length === 0) return {
+			reused: 0,
+			remaining
+		};
+		try {
+			this.chunks.setVectors(writes);
+		} catch {
+			return {
+				reused: 0,
+				remaining: [...remaining, ...writes.map((w) => ({
+					chunk_id: w.chunk_id,
+					text: w.text
+				}))]
+			};
+		}
+		for (const w of writes) {
+			const vec = bytesToFloat32(w.bytes);
+			if (vec !== null && vec.length === this.vstore.dim) this.vstore.add(w.chunk_id, vec);
+		}
+		return {
+			reused: writes.length,
+			remaining
+		};
+	}
+	/**
 	* Encode texts ONE AT A TIME, writing every `WRITE_BATCH` vectors in one transaction.
 	*
 	* The model call is deliberately NOT batched, and that is a MEASURED decision, not an omission:
@@ -11298,6 +11731,7 @@ var KnowledgeStore = class {
 				encoded += writes.length;
 			} catch {
 				failed += writes.length;
+				this.evictVectors(writes.map((w) => w.chunk_id));
 			}
 		}
 		if (failed > 0) retrievalLogger().warn(`kb index: ${String(failed)} of ${String(rows.length)} chunk vector(s) were not written — run kb_reindex to retry (the text/entity/FTS indexes are complete; only the semantic vectors are affected)`);
@@ -11771,7 +12205,8 @@ var KnowledgeStore = class {
 			const jaccard = [...qEntities].filter((e) => factSet.has(e)).length / union.size;
 			if (jaccard > 0) out.set(id, jaccard);
 		}
-		return out;
+		if (out.size <= cap) return out;
+		return new Map([...out].sort((a, b) => b[1] - a[1] || a[0] - b[0]).slice(0, cap));
 	}
 };
 const HEADING_RE = /^\s{0,3}(#{1,6})\s+(.+?)\s*$/;
@@ -12187,7 +12622,13 @@ const resultSymbol = (method) => fieldSymbol(method, "result");
 *
 * Carries BOTH members on purpose: the host's validator moved from `codec.schema.parse` (0.1.5) to
 * `codec.create()` (0.1.6), and each generation checks only its own. One shape therefore serves
-* either host — the same "one shape satisfies two revisions" trick the job plugin's `strict()` uses.
+* either host.
+*
+* Kept LOCAL — a two-line mirror of the base kit's `strictCodec`, not a runtime call — on purpose:
+* the Remote face is built at module load and must exist even when the base cannot be loaded at all,
+* so its construction may not depend on a runtime `import()` of the base. This is the "mirrors a
+* convention, so changing it takes a plugin release" side of the rule in the root AGENTS.md; the
+* shared, fixable-by-a-base-release code lives in `@avantf/dsh-plugin-base`'s kit.
 */
 function strict(schema, typeSymbol) {
 	return {
@@ -12207,11 +12648,11 @@ function parameter(method, name, schema, acceptsUndefined) {
 		...acceptsUndefined === void 0 ? {} : { acceptsUndefined }
 	};
 }
-const text = z$1.string();
-const count = z$1.number().int().optional();
-const optionalText = z$1.string().optional();
-const bool = z$1.boolean().optional();
-const textArray = z$1.array(z$1.string()).optional();
+const text = z.string();
+const count = z.number().int().optional();
+const optionalText = z.string().optional();
+const bool = z.boolean().optional();
+const textArray = z.array(z.string()).optional();
 /** One direct Remote method carrying a single `args` object parameter. */
 function direct(method, args) {
 	return {
@@ -12221,11 +12662,11 @@ function direct(method, args) {
 		method,
 		invocation: { kind: "direct" },
 		parameters: [parameter(method, "args", args)],
-		result: strict(z$1.any(), resultSymbol(method))
+		result: strict(z.any(), resultSymbol(method))
 	};
 }
 const descriptors = [
-	direct("remember", z$1.object({
+	direct("remember", z.object({
 		action: optionalText.optional(),
 		content: optionalText.optional(),
 		fact_id: count.optional(),
@@ -12233,7 +12674,7 @@ const descriptors = [
 		ttl_days: count.optional(),
 		reason: optionalText.optional()
 	})),
-	direct("recall", z$1.object({
+	direct("recall", z.object({
 		action: optionalText.optional(),
 		query: optionalText.optional(),
 		entity: optionalText.optional(),
@@ -12246,7 +12687,7 @@ const descriptors = [
 		limit: count.optional(),
 		max_tokens: count.optional()
 	})),
-	direct("admin", z$1.object({
+	direct("admin", z.object({
 		action: optionalText.optional(),
 		fact_id: count.optional(),
 		category: optionalText.optional(),
@@ -12259,7 +12700,7 @@ const descriptors = [
 		resolution: optionalText.optional(),
 		loser_fact_id: count.optional()
 	})),
-	direct("kb", z$1.object({
+	direct("kb", z.object({
 		action: optionalText.optional(),
 		text: optionalText.optional(),
 		source_uri: optionalText.optional(),
@@ -12274,7 +12715,7 @@ const descriptors = [
 		overwrite: bool.optional(),
 		adopt: bool.optional()
 	})),
-	direct("query", z$1.object({
+	direct("query", z.object({
 		query: text,
 		kind: optionalText.optional(),
 		domain: optionalText.optional(),
@@ -12282,11 +12723,11 @@ const descriptors = [
 		limit: count.optional(),
 		max_tokens: count.optional()
 	})),
-	direct("classifySource", z$1.object({ text: optionalText.optional() })),
-	direct("browseDir", z$1.object({ path: optionalText.optional() })),
-	direct("kbDomains", z$1.object({})),
-	direct("kbAddDomain", z$1.object({ domain: text })),
-	direct("openDoc", z$1.object({
+	direct("classifySource", z.object({ text: optionalText.optional() })),
+	direct("browseDir", z.object({ path: optionalText.optional() })),
+	direct("kbDomains", z.object({})),
+	direct("kbAddDomain", z.object({ domain: text })),
+	direct("openDoc", z.object({
 		doc_id: count,
 		target: optionalText.optional()
 	}))
@@ -12303,9 +12744,13 @@ function declared(name, schema) {
 * Host face: registered by the host half through `ctx.typert.register()`.
 *
 * The schema assertions name `TypertSchema['schema']` — the FIELD they are assigned to — rather
-* than this package's own `z.ZodType`. The two are different zod copies: the plugin pins
-* zod 4.4.3, the harness bundles 4.6.2, and `ZodType` gained members between them, so a cast to
-* the local `z.ZodType` could never be assignable and the annotation said nothing. Through
+* than this package's own `z.ZodType`. There are two PHYSICALLY different zod copies in play —
+* the workspace's (root catalog `zod: 4.6.5`, the one the plugin compiles against) and the one
+* inside the installed harness build — and two copies of the same major still have incompatible
+* type identities (the single-`zod` rule in the root `AGENTS.md` is the same lesson), so a
+* cast to the local `z.ZodType` could never be assignable and the annotation said nothing. Never
+* write a version number here again: it moves with the catalog, and a stale pair sends the next
+* reader to reason from the wrong premise. Through
 * `TypertSchema['schema']` the assertion is at least against the type the field actually
 * requires, and a future zod alignment (which would make the cast unnecessary) shows up here.
 */
@@ -12341,40 +12786,35 @@ const hostContribution = {
 	invocations: descriptors
 };
 //#endregion
-//#region lib/types/provision.js
+//#region lib/types/data_home.js
 /**
-* This plugin's compatibility spec, and the wiring that runs it.
-*
-* The rules, the probes, the report and the post-registration check all live in
-* `@avantf/dsh-compat` (shared with the rest of the family). What stays here is only what is true of
-* THIS plugin: the services and methods it calls, the dsh packages that identify the host, the wire
-* schema names and tool names that must be visible afterwards, the events it listens to, and the
-* Chinese report a user reads. See `DESIGN.md` §12.1.
-*
-* **Who obtains the base.** Not this module. The family framework `@avantf/dsh-envinit` provisions
-* `@avantf/dsh-compat` as the `mem:compat` manifest item and hands back the directory it landed in
-* (`src/envinit.ts`); this module is given the loaded module and derives everything from it. That is
-* the whole point of the framework: acquisition (resolve → managed copy → verified download →
-* atomic publish) is one shared mechanism, and the plugin only declares what it needs.
+* The plugin's data root, resolved through the FAMILY's layers.
 *
-* The base therefore has NO import path of its own here — not even a dynamic one. A static `import`
-* would throw `ERR_MODULE_NOT_FOUND` while the artifact was being evaluated (the base is not a
-* runtime dependency of the published plugin any more), and a bare dynamic `import()` would bypass
-* the framework's managed copy. The plugin loads the module the framework resolved, by file URL.
+* The profile's `config.dataHome` is CONFIGURATION, so it takes the CONFIGURED layer: ⑤ an explicit
+* caller value → ④ `$AVANTF_HOME` → ② this configured value → `~/.avantf`. Handing it straight to the
+* engine's explicit slot instead — which is what this plugin used to do — promotes ② above ④, and the
+* same profile then resolves to two different directories depending on which half of the family reads
+* it: the work plugin resolves the same knob through its configured layer, so with `$AVANTF_HOME` set
+* work read `<env>/prompts` while this plugin read `<config>/prompts`. That directory is SHARED (both
+* plugins' editable prompt files live in it), so "the file you edited is read by one plugin and not
+* the other" is a real failure, not a nuance. `AGENTS.md` 「边界与路径」 states the rule this
+* implements: the configured value travels in the config layer, never in the explicit one.
 *
-* The plugin computes the gate's verdict here and hands it to the engine as plain data
-* (`{ load, status, reason }`), so the inlined engine bundle never imports the base either.
+* The engine's own copy of the rule does the work (it is the one the CLI and MCP resolve with, and
+* `test/family_pin.spec.ts` pins it against the base kit's). This module exists so the plugin's USE of
+* it is testable without the DSH harness: the entry module imports `@deepseek-ai/*` at load, which
+* resolves only inside a harness workspace.
 *
-* @module @avantf/dsh-mem/provision
+* @module data_home
 */
-/** The base package id, named here too so the item declaration and the spec need no import. */
-const COMPAT_PACKAGE = "@avantf/dsh-compat";
-/**
-* Fallback range for `@avantf/dsh-compat`, used only when `package.json` has lost the dependency
-* entry. The manifest is the single source of truth (`compatRange()`); `scripts/pack-plugin.mjs`
-* pins this constant to it so the two cannot drift.
-*/
-const COMPAT_RANGE = "^0.1.0";
+/** Layer ② for the configured value; `$AVANTF_HOME` (④) and any explicit value (⑤) still outrank it. */
+function configDataHome(configured) {
+	return resolveDataHome({ common: { dataHome: configured ?? "" } });
+}
+//#endregion
+//#region lib/types/provision.js
+/** The base package id, named here so the gate's messages need no import of it. */
+const COMPAT_PACKAGE = "@avantf/dsh-plugin-base";
 /**
 * The services this plugin calls, with the methods it calls on them.
 *
@@ -12438,27 +12878,6 @@ function warn(log, message) {
 	} catch {}
 }
 /**
-* The range of `@avantf/dsh-compat` this build is written against.
-*
-* Read from THIS plugin's manifest, which is the single source of truth — the framework does not
-* pick it, and a hardcoded constant would silently keep provisioning an old range after the family
-* publishes a new one. The constant is only a fallback for a manifest that lost the entry.
-*
-* It lives in `devDependencies`, deliberately. Nothing imports the base: the framework fetches it
-* into its own managed home and this plugin loads it from there, so a RUNTIME dependency would
-* install a second copy on every consumer that no code path ever loads. `devDependencies` still
-* ships in the packed manifest (pnpm keeps it, rewriting `catalog:` like any other field), so the
-* range travels with the artifact; it just is not installed.
-*/
-async function compatRange(manifestUrl = new URL("../package.json", import.meta.url)) {
-	try {
-		const raw = JSON.parse(await readFile(manifestUrl, "utf8"));
-		const declared = raw.devDependencies?.["@avantf/dsh-compat"] ?? raw.dependencies?.["@avantf/dsh-compat"];
-		if (typeof declared === "string" && declared.trim() !== "") return declared;
-	} catch {}
-	return COMPAT_RANGE;
-}
-/**
 * Build the plugin-specific half of the gate from a loaded base.
 *
 * Called ONCE per process (the loaded runtime is cached by `src/envinit.ts`), which is what makes the
@@ -12556,7 +12975,8 @@ function registerCompatMegaphone(ctx, verdict, log, compat) {
 			heading: "记忆插件未加载：与当前 dsh 的兼容性检查未通过，插件已拒绝加载（不注册服务、工具、prompt 段与真实 typert face）。",
 			warningsLabel: "风险提示：",
 			warnings: verdict.warnings,
-			fix: "修复：在本仓库重建（`pnpm build:dsh`），或把 `@deepseek-ai/dsh` 换回本构建声明的版本。"
+			fix: "修复：在本仓库重建（`pnpm build:dsh`），或把 `@deepseek-ai/dsh` 换回本构建声明的版本。",
+			logPointer: (prefix) => `完整诊断见宿主日志里 ${prefix} 开头的行。`
 		})
 	});
 }
@@ -12577,7 +12997,7 @@ function verifyRegisteredFaces(input) {
 		toolNames: input.toolNames
 	});
 }
-const PACKAGE = "@avantf/dsh-envinit";
+const PACKAGE = "@avantf/dsh-plugin-base";
 function parseVersion(input) {
 	const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(input.trim());
 	if (match === null) return void 0;
@@ -12803,7 +13223,7 @@ async function ensureFramework(options) {
 			warn(`supportedRange must be a string; got ${typeof options.supportedRange}`);
 			return;
 		}
-		const supported = options.supportedRange ?? "^0.1.3";
+		const supported = options.supportedRange ?? ">=0.3.0 <1.0.0";
 		let dir;
 		try {
 			dir = dirname(createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`));
@@ -12889,32 +13309,112 @@ function rangeOf(value) {
 	return typeof range === "string" && range.trim() !== "" ? range : void 0;
 }
 //#endregion
+//#region lib/types/interface_gate.js
+/** Read one member without letting a hostile module's getter escape. */
+function member(module, name) {
+	try {
+		return module?.[name];
+	} catch {
+		return;
+	}
+}
+function cannotTell(reason) {
+	return {
+		status: "cannot-tell",
+		reason
+	};
+}
+/**
+* Whether the base's shared capabilities may be used under `verdict`.
+*
+* The ONE mapping from the gate's verdict to the loader's decision, exported so it is asserted
+* directly and the loader and its test cannot drift: only `incompatible` withholds the base;
+* `cannot-tell` does not, because it is not a negative answer. A `false` here is still a DEGRADATION
+* (own prompt defaults, gate skipped, legacy provisioning), never a refused mount.
+*/
+function baseIsUsable(verdict) {
+	return verdict.status !== "incompatible";
+}
+/**
+* Where the build's bake record sits when no explicit URL is given: beside the built ENTRY
+* (`lib/index.js`), which is where `scripts/link-envinit.mjs` writes it. A per-file `tsc` emit of
+* this module lives one directory below that entry and looks one level up; the first readable record
+* wins. Under `vitest` (running from `src/`) neither exists, which is the correct "not baked".
+*/
+const BAKED_CANDIDATES = ["./interface-version.json", "../interface-version.json"];
+/**
+* Read this artifact's baked requirement through the loaded base's own reader.
+* @param read - the base's `readInterfaceRequirement`, taken off the loaded module.
+* @param bakedUrl - test seam: read EXACTLY this record instead of walking {@link BAKED_CANDIDATES}.
+*/
+function requirementOf(read, bakedUrl) {
+	const candidates = bakedUrl === void 0 ? BAKED_CANDIDATES.map((relative) => new URL(relative, import.meta.url)) : [bakedUrl];
+	for (const url of candidates) {
+		let requirement;
+		try {
+			requirement = read(url);
+		} catch {
+			continue;
+		}
+		const version = requirement?.interfaceVersion;
+		if (typeof version === "number" && Number.isInteger(version) && version > 0) return { interfaceVersion: version };
+	}
+}
+/**
+* Ask the loaded base whether it implements the interface generation this artifact was built for.
+*
+* @param module - the loaded base module (only `checkInterface` / `readInterfaceRequirement` are
+*   touched, each through a guarded read).
+* @param bakedUrl - test seam: the bake record to read; production leaves it undefined.
+* @returns a verdict that is never `incompatible` unless BOTH sides were readable and differ, and
+*   never a throw.
+*/
+function interfaceVerdict(module, bakedUrl) {
+	const check = member(module, "checkInterface");
+	const read = member(module, "readInterfaceRequirement");
+	if (typeof check !== "function" || typeof read !== "function") return cannotTell("the loaded base has no interface gate (checkInterface / readInterfaceRequirement missing) — it predates the runtime interface contract, so which generation it implements cannot be told");
+	const requirement = requirementOf(read, bakedUrl);
+	if (requirement === void 0) return cannotTell("this build has no baked interface requirement (lib/interface-version.json is missing or malformed), so the runtime interface gate cannot run");
+	let verdict;
+	try {
+		verdict = check(requirement.interfaceVersion, module);
+	} catch {
+		return cannotTell("the loaded base threw while judging the interface generation");
+	}
+	const status = verdict?.status;
+	if (status !== "ok" && status !== "incompatible" && status !== "cannot-tell") return cannotTell("the loaded base returned no usable interface verdict");
+	return verdict;
+}
+//#endregion
 //#region lib/types/envinit.js
 /**
-* Environment initialisation for the memory plugin, through the family framework
-* `@avantf/dsh-envinit`.
+* Environment initialisation for the memory plugin, through the family base
+* `@avantf/dsh-plugin-base`.
 *
-* The shape is fixed by the framework's DESIGN §7.2 and is the same for every plugin:
+* The shape is fixed by the base's DESIGN §7.2 and is the same for every plugin:
 *
-*   bootstrap (inlined) → load the framework → register + declare → wait for the `blocking` set →
-*   dispatch the `background` set → the plugin's own pre-mount check.
+*   bootstrap (inlined) → load the base → register + declare the remaining resources → dispatch the
+*   `background` set → the plugin's own pre-mount check.
 *
-* What this plugin needs, in three phases:
+* What this plugin needs, in two phases:
 *
-*   1. **`mem:compat`** (`npm-package`, `startup: 'blocking'`) — the family compatibility gate
-*      `@avantf/dsh-compat`. It has to be there BEFORE anything is registered, because a proven
-*      incompatible host must refuse the mount with nothing half-registered. This replaces the
-*      bespoke self-heal the plugin used to run itself (`@avantf/mem-provision`'s
-*      `ensureCompatBase`), whose private root (`<dataHome>/dsh-compat/**`) the framework
-*      deliberately does not read.
+*   1. **The gate, straight from the base** — the family compatibility gate is part of
+*      `@avantf/dsh-plugin-base` and arrived WITH the module the bootstrap loaded. There is no
+*      `mem:compat` item, no npm download and no managed `<home>/compat/**` copy any more; the base's
+*      `compat` module provides the rules, probes, report and post-registration check, and
+*      `runtimeFromCompat(framework)` derives this plugin's spec from it. The gate has to be runnable
+*      BEFORE anything is registered, because a proven incompatible host must refuse the mount with
+*      nothing half-registered. This replaces the bespoke self-heal the plugin used to run itself
+*      (`@avantf/mem-provision`'s `ensureCompatBase`), whose private root (`<dataHome>/dsh-compat/**`)
+*      the base deliberately does not read.
 *   2. **`mem:pandoc`** (`binary-archive`, `startup: 'background'`) — the documented "expensive but
 *      not startup-blocking" resource. It is declared AFTER the runtime exists, because its spec
 *      comes from the resolved config (`tools.auto_install`, `tools.mirror`), and it is dispatched
 *      without waiting: the caller continues its own initialisation and hooks the outcome through
 *      `onSettled`.
 *   3. **`mem:model`** (`model-cache`, `startup: 'background'`) — the embedding model. It uses the
-*      framework's `flat` layout, whose files land at `<root>/<repo>/<file>` — exactly the shape
-*      `@huggingface/transformers` reads under its `cacheDir` — so the runtime loads the framework's
+*      base's `flat` layout, whose files land at `<root>/<repo>/<file>` — exactly the shape
+*      `@huggingface/transformers` reads under its `cacheDir` — so the runtime loads the base's
 *      copy instead of fetching a second one. For the default repo the file list is the narrow set
 *      the runtime actually opens (see {@link MODEL_FILES}); any other repo omits the list, because
 *      a fixed six-file list made the item fail for a repo whose file set differs. The endpoint is
@@ -12925,24 +13425,23 @@ function rangeOf(value) {
 *
 * Two hard rules:
 *
-*   - **The framework is never statically imported.** Only `import type` and the inlined bootstrap
+*   - **The base is never statically imported.** Only `import type` and the inlined bootstrap
 *     are static; the value comes from `loadFramework()`. A top-level value import would throw before
 *     the bootstrap ran — exactly the broken-tree case the bootstrap exists for.
-*   - **Nothing here refuses the mount.** "Cannot tell" is not "incompatible": a missing framework,
+*   - **Nothing here refuses the mount.** "Cannot tell" is not "incompatible": a missing base,
 *     an unavailable gate or a failed resource is a WARNING, and the plugin mounts with its tools,
 *     service, prompt and Remote face intact.
 *
 * @module @avantf/dsh-mem/envinit
 */
-/** The framework package, as declared in this plugin's `peerDependencies`. */
-const FRAMEWORK_PACKAGE = "@avantf/dsh-envinit";
+/** The family base package, as declared in this plugin's `peerDependencies`. */
+const FRAMEWORK_PACKAGE = "@avantf/dsh-plugin-base";
 /** The plugin namespace every item is declared under (`<plugin>:<name>`, framework DESIGN §13.4). */
 const PLUGIN = "mem";
 /**
 * The item ids. `resolve()` / `onSettled` are keyed by them, so the DSH plugin compares against these
 * names rather than re-spelling literals.
 */
-const COMPAT_ITEM = "mem:compat";
 const PANDOC_ITEM = "mem:pandoc";
 const MODEL_ITEM = "mem:model";
 /**
@@ -13040,70 +13539,6 @@ function provisionLogger(log) {
 	};
 }
 /**
-* The file URL to `import()` for a managed npm copy.
-*
-* The framework hands back the package DIRECTORY (`<version dir>/node_modules/<name>`), and a
-* directory is not importable, so the entry is read from the copy's own manifest the way Node would:
-* `exports["."]` first, then `main`.
-*/
-async function entryUrlOf(packageDir) {
-	let manifest;
-	try {
-		manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
-	} catch {
-		return;
-	}
-	const dot = manifest.exports?.["."];
-	const fromExports = typeof dot === "string" ? dot : dot?.default;
-	return pathToFileURL(join(packageDir, typeof fromExports === "string" ? fromExports : typeof manifest.main === "string" ? manifest.main : "./index.js")).href;
-}
-/**
-* The resolved directory of a peer in THIS plugin's tree.
-*
-* The framework must reuse the host's own copy for identity-sensitive peers, and it cannot find them
-* by itself: its resolver looks at `process.cwd()` and at its own module URL — neither is the
-* plugin's tree. So the caller hands the directory over explicitly (`NpmPackageSpec.peers[].dir`);
-* without it the item fails with `peer/unsatisfied`.
-*/
-function peerDirOf(name) {
-	const require = createRequire(import.meta.url);
-	try {
-		return dirname(require.resolve(`${name}/package.json`));
-	} catch {
-		try {
-			let dir = dirname(require.resolve(name));
-			for (let depth = 0; depth < 6; depth += 1) {
-				if (dir.endsWith(`/${name}`)) return dir;
-				const parent = dirname(dir);
-				if (parent === dir) break;
-				dir = parent;
-			}
-		} catch {}
-	}
-}
-/** The `mem:compat` item: the family compatibility gate, waited for before anything registers. */
-function compatItem(framework, range, zodDir) {
-	return {
-		id: COMPAT_ITEM,
-		kind: framework.NPM_PACKAGE_KIND,
-		spec: {
-			name: COMPAT_PACKAGE,
-			range,
-			peers: [{
-				name: "zod",
-				...zodDir === void 0 ? {} : { dir: zodDir }
-			}]
-		},
-		target: { root: "runtime" },
-		onMissing: {
-			atStartup: "degrade",
-			atUse: "degrade"
-		},
-		startup: "blocking",
-		schemaVersion: framework.ITEM_SCHEMA_VERSION
-	};
-}
-/**
 * The `mem:pandoc` item: the pinned pandoc release as a `binary-archive`.
 *
 * The packs are `@avantf/mem-provision`'s (`PANDOC_PACKS`), the single source of the URLs and the
@@ -13229,41 +13664,25 @@ async function loadOnce(options) {
 		warn(options.log, `${OWN_PREFIX} WARNING — ${FRAMEWORK_PACKAGE} could not be made available; the plugin falls back to its own provisioning and mounts anyway`);
 		return;
 	}
-	const provisioner = framework.createProvisioner({
-		home,
-		envinitRange: range,
-		logger: provisionLogger(options.log),
-		policy: {
-			autoDownload,
-			deadlineMs
-		}
-	});
-	provisioner.register(framework.npmPackageProvider());
-	provisioner.declare({
-		plugin: PLUGIN,
-		items: [compatItem(framework, await compatRange(), peerDirOf("zod"))]
-	});
-	await provisioner.ensure({
-		only: [COMPAT_ITEM],
-		deadlineMs,
-		onSettled: (entry) => {
-			if (entry.action === "failed") warn(options.log, `${OWN_PREFIX} WARNING — ${COMPAT_ITEM} failed (${String(entry.code)}): ${entry.reason ?? ""}`);
+	{
+		const verdict = interfaceVerdict(framework);
+		if (!baseIsUsable(verdict)) {
+			warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? "the loaded base implements another interface generation"}; the base's shared capabilities are NOT used (own prompt defaults, gate skipped, legacy provisioning) and the plugin mounts anyway`);
+			return;
 		}
-	});
-	const disposers = [provisioner];
+		if (verdict.status === "cannot-tell") warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? "the interface generation cannot be told"}; using the loaded base anyway ("cannot tell" is never "incompatible")`);
+	}
+	const disposers = [];
 	let compat;
-	const state = provisioner.resolve(COMPAT_ITEM);
-	if (state.state !== "ready") warn(options.log, `${OWN_PREFIX} WARNING — ${COMPAT_PACKAGE} is unavailable (${describeState(state)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
-	else try {
-		const module = options.compatModule ?? await importCompat(state.handle.dir);
-		if (module === void 0) warn(options.log, `${OWN_PREFIX} WARNING — ${COMPAT_PACKAGE} has no readable entry at ${state.handle.dir}; the compatibility gate is SKIPPED`);
-		else compat = runtimeFromCompat(module);
+	try {
+		compat = runtimeFromCompat(options.compatModule ?? framework);
 	} catch (error) {
-		warn(options.log, `${OWN_PREFIX} WARNING — ${COMPAT_PACKAGE} could not be imported (${reasonOf(error)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
+		warn(options.log, `${OWN_PREFIX} WARNING — the ${COMPAT_PACKAGE} compatibility gate could not be initialised (${reasonOf(error)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
 	}
 	let disposed = false;
 	return {
 		home,
+		kit: framework,
 		compat,
 		roots: {
 			tools: join(home, "tools"),
@@ -13316,19 +13735,6 @@ async function loadOnce(options) {
 		}
 	};
 }
-/** One line describing why a non-ready item is not ready, safe to put in a WARNING. */
-function describeState(state) {
-	if (state.state === "ready") return `ready (${state.handle.source})`;
-	if (state.state === "failed" || state.state === "skipped") return `${state.state}: ${state.code}${state.detail === void 0 ? "" : ` (${state.detail})`}`;
-	if (state.state === "pending") return "pending (still being fetched)";
-	return state.state;
-}
-/** Load the managed copy's entry by file URL; `undefined` when it has no readable entry. */
-async function importCompat(packageDir) {
-	const url = await entryUrlOf(packageDir);
-	if (url === void 0) return void 0;
-	return await import(url);
-}
 //#endregion
 //#region lib/types/open.js
 /**
@@ -13497,7 +13903,7 @@ function zodDef(schema) {
 function jsonSchemaOf(schema) {
 	if (typeof schema?.safeParse !== "function") return void 0;
 	try {
-		return z$1.toJSONSchema(schema, {
+		return z.toJSONSchema(schema, {
 			io: "input",
 			unrepresentable: "any"
 		});
@@ -13663,9 +14069,9 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	done = true;
 };
 const name = "avantf-mem";
-const Config = z.object({
-	mode: z.union([z.const("cordis"), z.const("mcp")]).default("cordis"),
-	dataHome: z.string()
+const Config = z$1.object({
+	mode: z$1.union([z$1.const("cordis"), z$1.const("mcp")]).default("cordis"),
+	dataHome: z$1.string()
 });
 /**
 * Facts whose entity/triple rows the heartbeat may rebuild per beat.
@@ -13864,6 +14270,16 @@ let AvantfMemGateway = (() => {
 			super(ctx, "avantfMem");
 			this.rt = rt;
 		}
+		/**
+		* Run one already-validated tool call and wrap the answer in the contract envelope.
+		*
+		* `T` is the payload the tool key is DECLARED to answer, spelled at each `@Remote` below; this used
+		* to be `unknown` everywhere, which made the host half the one seam in the type chain where nothing
+		* said what crosses the wire. The single `as T` is unavoidable and is the honest part: the dispatch
+		* table is keyed by `ToolSpec.key` (a `string`), so its result is `unknown` by construction. Naming
+		* the type is what turns "the client assumed a shape" into "the engine's own type is what the host
+		* claims to send".
+		*/
 		async call(key, spec, payload) {
 			const parsed = spec.input.safeParse(payload);
 			if (!parsed.success) return validationError(spec.name, parsed.error.issues);
@@ -13879,6 +14295,11 @@ let AvantfMemGateway = (() => {
 				};
 			}
 		}
+		/**
+		* Each payload is written as the ENGINE type that produces it (`StoreResult<…>`, or a contract
+		* interface), never as a hand-copied shape: if a store method's result changes, the declaration
+		* here stops compiling instead of quietly misdescribing the wire.
+		*/
 		remember(args) {
 			const payload = defined(args);
 			return this.call("remember", REMEMBER_TOOL, {
@@ -13900,6 +14321,12 @@ let AvantfMemGateway = (() => {
 				...payload
 			});
 		}
+		/**
+		* The one method that keeps `unknown`, and deliberately: its payload is whichever of the seven
+		* corpus actions the caller asked for (a page, one document, an ingest report, a conflict report, a
+		* reindex plan …), so there is no single engine type to name. The engine's `KbDispatch` spells all
+		* seven out; the client names its expectation at each call site (`callRemote<…>(…)`).
+		*/
 		kb(args) {
 			return this.call("kb", KB_TOOL, defined(args));
 		}
@@ -14105,8 +14532,8 @@ function startManagedResources(env, rt, logger, waitFor) {
 		if (entry.action === "failed" || entry.action === "skipped") {
 			logger.warn(`envinit: ${entry.id} is ${entry.action} (${String(entry.code)}${entry.reason === void 0 ? "" : ` — ${entry.reason}`})`);
 			if (entry.id === "mem:pandoc") {
-				const fallback = legacyToolsDir(rt, env);
-				logger.warn(`envinit: falling back to ${fallback} for pandoc (override with tools.dir or AVANTF_PANDOC)`);
+				const fallback = resolveToolsDir(parseToolsConfig(rt.config.common.tools));
+				logger.warn(`envinit: pandoc unavailable from the framework; the converter will use ${fallback} (override with tools.dir or AVANTF_PANDOC)`);
 				setPandocProvisioning({
 					toolsDir: fallback,
 					mirror: rt.config.common.tools.mirror,
@@ -14120,21 +14547,6 @@ function startManagedResources(env, rt, logger, waitFor) {
 		logger.info(`envinit: ${entry.id} ${entry.action} (${entry.source}${entry.version === void 0 ? "" : ` ${entry.version}`})`);
 	});
 }
-/**
-* The tools directory to use when the framework did NOT deliver pandoc.
-*
-* Resolved through the provisioning layer's own `resolveToolsDir`, so the environment hatch
-* (`AVANTF_TOOLS_DIR`) and the `~` expansion behave here exactly as they do everywhere else — the
-* converter hands `settings.toolsDir` to `ensurePandoc` VERBATIM (`pandocBinary`), so whatever this
-* returns is the final word for the process. `managedRoots` replaced the built-in default, so
-* `config.common.tools.dir` equals the family root even when the operator never touched it; only a
-* resolved value that is STILL the family root means "nobody chose one", and only then may the
-* legacy default apply.
-*/
-function legacyToolsDir(rt, env) {
-	const resolved = resolveToolsDir(parseToolsConfig(rt.config.common.tools));
-	return resolved === env.roots.tools ? defaultToolsDir() : resolved;
-}
 async function apply(ctx, config) {
 	const logger = hostLogger(ctx);
 	const env = await loadEnvinit({ log: logger });
@@ -14144,7 +14556,7 @@ async function apply(ctx, config) {
 	}
 	const compat = env?.compat;
 	let verdict;
-	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is ABSENT (@avantf/dsh-compat unavailable — see the `compat:` WARNING above); mounting the full plugin anyway");
+	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is ABSENT (@avantf/dsh-plugin-base unavailable — see the WARNING above); mounting the full plugin anyway");
 	else {
 		const run = provision(ctx, logger, compat);
 		if (!run.verdict.load) {
@@ -14156,11 +14568,12 @@ async function apply(ctx, config) {
 	}
 	const toolSpecs = TOOL_SPECS;
 	if (config.mode === "mcp") logger.warn("config mode=mcp is not served in-process — mounting the cordis toolset; run @avantf/mem-mcp standalone for MCP");
-	logger.info(`plugin mount: mode=${config.mode ?? "cordis"} dataHome=${config.dataHome ?? "(unset → AVANTF_HOME, else ~/.avantf)"}`);
+	const dataHome = configDataHome(config.dataHome);
+	logger.info(`plugin mount: mode=${config.mode ?? "cordis"} dataHome=${dataHome} (configured ${config.dataHome ?? "unset"})`);
 	let rt;
 	try {
 		rt = buildRuntime({
-			dataHome: config.dataHome,
+			dataHome,
 			logger,
 			...env === void 0 ? {} : { managedRoots: {
 				tools: env.roots.tools,
@@ -14217,14 +14630,25 @@ async function apply(ctx, config) {
 		logger.info(`trust heartbeat: every ${heartbeatMinutes}min (active-day clock + lifecycle sweep)`);
 		return () => clearInterval(timer);
 	});
-	for (const section of [
-		MEMORY_PROMPT_SECTION,
-		KNOWLEDGE_PROMPT_SECTION,
-		KB_EDIT_PROMPT_SECTION
-	]) {
+	const promptDir = join(rt.config.home, "prompts");
+	const kit = env?.kit;
+	const loadedPrompts = kit?.PromptFiles === void 0 ? promptFileSpecs().map((spec) => ({
+		file: spec.file,
+		path: join(promptDir, spec.file),
+		text: spec.fallback,
+		source: "default",
+		wrote: false
+	})) : new kit.PromptFiles({
+		dir: promptDir,
+		logger
+	}).load(promptFileSpecs());
+	const promptSections = buildPromptSections(loadedPrompts);
+	for (const section of promptSections) {
 		ctx.systemPrompt.section(section);
 		logger.info(`prompt section registered: ${section.name} (order ${String(section.order)})`);
 	}
+	for (const warning of promptTextWarnings(promptSections)) logger.warn(`prompt text: ${warning}`);
+	logger.info(`prompt files: ${promptDir} (${loadedPrompts.map((entry) => `${entry.file}:${entry.source}`).join(", ")})`);
 	const hints = /* @__PURE__ */ new WeakMap();
 	ctx.on("agent/inbox/inserted", (payload) => {
 		const agent = payload.agent;