@cerefox/memory 1.14.1 → 1.14.2

package/dist/bin/cerefox.js

@@ -7400,7 +7400,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 });
 
 // src/meta.ts
-var PKG_VERSION = "1.14.1";
+var PKG_VERSION = "1.14.2";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -23282,16 +23282,18 @@ function applyByteBudget(rows, maxBytes) {
   const accepted = [];
   let usedBytes = 0;
   let truncated = false;
-  for (const row of rows) {
+  let cut = rows.length;
+  for (const [i, row] of rows.entries()) {
     const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
     if (usedBytes + rowBytes > maxBytes) {
       truncated = true;
+      cut = i;
       break;
     }
     accepted.push(row);
     usedBytes += rowBytes;
   }
-  return { accepted, truncated, usedBytes };
+  return { accepted, dropped: rows.slice(cut), truncated, usedBytes };
 }
 function extractConflictHashes(message) {
   return {
@@ -25774,7 +25776,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.14.1", CEREFOX_VERSION = "1.14.1", EF_LAST_CHANGED = "1.14.0";
+var EF_VERSION = "1.14.2", CEREFOX_VERSION = "1.14.2", EF_LAST_CHANGED = "1.14.2";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -25923,9 +25925,9 @@ __export(exports_onnx_embedder, {
   onnxEmbed: () => onnxEmbed,
   warmup: () => warmup
 });
-import { existsSync as existsSync9, mkdirSync as mkdirSync3 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync4 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join9 } from "node:path";
 function nomicPrefix(role) {
   return role === "query" ? "search_query: " : "search_document: ";
 }
@@ -25937,7 +25939,7 @@ function getCacheDir() {
   const env2 = globalThis.process?.env ?? {};
   if (env2.CEREFOX_MODELS_DIR)
     return env2.CEREFOX_MODELS_DIR;
-  return join8(homedir5(), ".cerefox", "models");
+  return join9(homedir6(), ".cerefox", "models");
 }
 async function loadTransformers() {
   if (transformersModule)
@@ -25945,8 +25947,8 @@ async function loadTransformers() {
   const spec = "@huggingface/transformers";
   transformersModule = await import(spec);
   const dir = getCacheDir();
-  if (!existsSync9(dir))
-    mkdirSync3(dir, { recursive: true });
+  if (!existsSync10(dir))
+    mkdirSync4(dir, { recursive: true });
   transformersModule.env.cacheDir = dir;
   transformersModule.env.allowLocalModels = true;
   transformersModule.env.allowRemoteModels = true;
@@ -55761,12 +55763,12 @@ var init_partial_edits2 = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **15 core MCP tools** (14 with CLI equivalents — `cerefox_get_help` is MCP-only), plus 4 dormant relation tools that appear only when `relations_enabled` is on. For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `author` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part`, `author` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required), `author` |\n| `cerefox_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |\n| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete; no-op if not deleted) | `document_id` (required), `reason` (recorded in the audit log), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part`, `author` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required), `author` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type`, `author` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required), `author` |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `by_author` (filter), `operation`, `since`, `author` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`** to your name on every call, reads and writes alike (e.g., "Claude Code", "archiver"). Same parameter on every tool. (`requestor` is still accepted everywhere as the pre-1.13.1 alias.) On the CLI it is `--author` on every command too (plus `--author-type` on writes); or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --author "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --author "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --author "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --author "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_insert` | `cerefox document insert <id> -t "<text>" -p <position> -a "<anchor-heading>" -e "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_edit` | `cerefox document edit-parts <id> --operations \'<json>\' -e "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_delete_document` | `cerefox document delete <id> --reason "<why>" --author "<your-name>" --author-type agent --yes` (confirms interactively instead of requiring the hash) |\n| `cerefox_restore_document` | `cerefox document restore <id> --reason "<why>" --author "<your-name>" --author-type agent` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --author "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --author "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--author "<your-name>"` (the same flag; `--requestor` still works as a hidden alias)\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**\n  Ingest replaces the whole document, so re-sending it to set one tag carries the\n  full transcription risk for no reason. The metadata tool merges: the keys you\n  pass are set, everything else is left alone, so you do not need to read the\n  document first and cannot drop a tag another agent set. Pass `null` as a value\n  to remove a key.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. **Every `cerefox_get_help()` response\n  begins with the server\'s version and the operations it registers** — you do\n  not need a special topic, and the *absence* of that block is itself an answer:\n  a server that does not print it predates v1.5.0. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\n- Long inline bodies can arrive with literal `\\n`/`\\"` (the author over-escaped; Cerefox stores bytes faithfully). For long or quote-dense content, ingest from a file or build incrementally with `cerefox_insert`; read back multi-line writes.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **15 core MCP tools** (14 with CLI equivalents — `cerefox_get_help` is MCP-only), plus 4 dormant relation tools that appear only when `relations_enabled` is on. For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `author` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part`, `author` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required), `author` |\n| `cerefox_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |\n| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete; no-op if not deleted) | `document_id` (required), `reason` (recorded in the audit log), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section\'s text | `document_id` (required), `outline`, `section`, `section_part`, `author` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required), `author` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type`, `author` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required), `author` |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `by_author` (filter), `operation`, `since`, `author` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.\n\n## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`** to your name on every call, reads and writes alike (e.g., "Claude Code", "archiver"). Same parameter on every tool. (`requestor` is still accepted everywhere as the pre-1.13.1 alias.) On the CLI it is `--author` on every command too (plus `--author-type` on writes); or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **`max_bytes` has to fit a whole document.** Search returns COMPLETE documents, so a budget smaller than the top hit fits nothing. You get a header-only list saying so (never "No results found." — that means the store really has nothing). Raise `max_bytes`, or read one document with `cerefox_get_document` using `outline: true` or `section`.\n6. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n7. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n8. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\n9. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n10. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n11. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n12. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n13. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --author "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --author "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --author "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --author "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_insert` | `cerefox document insert <id> -t "<text>" -p <position> -a "<anchor-heading>" -e "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_edit` | `cerefox document edit-parts <id> --operations \'<json>\' -e "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_delete_document` | `cerefox document delete <id> --reason "<why>" --author "<your-name>" --author-type agent --yes` (confirms interactively instead of requiring the hash) |\n| `cerefox_restore_document` | `cerefox document restore <id> --reason "<why>" --author "<your-name>" --author-type agent` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --author "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json \'{...}\'`, `--replace`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --author "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--author "<your-name>"` (the same flag; `--requestor` still works as a hidden alias)\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n\n## Timestamps are UTC\n\nEvery timestamp Cerefox returns — `created_at` on audit entries, version\nhistory, document metadata — is **UTC**, and now carries its `Z` marker so it\ncannot be mistaken for local time.\n\n**When you write a date into a document\'s CONTENT, use your own clock, not a\nCerefox timestamp.** These are different things: a timestamp records when the\nserver stored something; a date in a log entry or a heading is authored content\nand belongs to your timezone. An agent working a Pacific afternoon read\n`2026-08-11` from version history, wrote "8/11" into its entries, and put a\nday\'s work in the future — the timestamp was correct, and copying it into\ncontent was not.\n\nCerefox deliberately does not convert to local time on the API or MCP paths.\n"Local" has no server-side meaning: the remote MCP server runs in a cloud\nfunction whose local time *is* UTC, while a local MCP server runs in yours, so\nthe same document would report two different times depending on transport. The\nweb UI converts because a browser knows the viewer\'s timezone; nothing\nserver-side does.\n\n## Mistakes that have actually happened\n\nEach of these comes from a real agent session, and each is easy to make.\n\n- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.\n  Before sending, check that the tool name matches the intent: if the intent is\n  "change one section", the call is `cerefox_edit` with `replace_section`. A\n  section-sized edit sent as a full ingest truncated a 13,000-character index to\n  a single word. It was recovered from version history within the minute, but\n  only because it was noticed immediately.\n\n- **Do not include the anchor\'s own heading in your text.** `replace_section`\n  keeps the heading and `insert` places your text inside the section, so\n  including it produces two. This is now refused rather than silently applied,\n  but the shape is worth knowing: it happened twice in one session, the second\n  time while trying to repair the first. A *deeper* sub-heading inside your text\n  is fine.\n\n- **Content between sections belongs to the section ABOVE it.** A section runs\n  to the next heading of the same or higher level, so a `---` rule, a note, or\n  any trailing text sitting just above the next heading is part of the section\n  before it — even when it visually reads as belonging below. Replacing that\n  section takes it too. An agent hit exactly this: a `---` that separated two\n  major sections disappeared when the section above it was replaced. The write\n  was correct by the addressing rules; the surprise is that "the end of this\n  section" is further down the page than it looks. Note the loss warning will\n  not catch it if your replacement text is longer than what it replaced, since\n  there is then no net loss to report.\n\n- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**\n  Ingest replaces the whole document, so re-sending it to set one tag carries the\n  full transcription risk for no reason. The metadata tool merges: the keys you\n  pass are set, everything else is left alone, so you do not need to read the\n  document first and cannot drop a tag another agent set. Pass `null` as a value\n  to remove a key.\n\n- **Never partial-edit to fix a partial edit.** If a write leaves unexpected\n  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,\n  and re-ingest cleanly. Repairing edits with more edits compounds the damage.\n\n- **A rejected batch is safe.** Operations in one `cerefox_edit` are\n  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a\n  retry, not data — so prefer one call for changes that belong together, and do\n  not split a batch to "make it more likely to succeed".\n\n- **Read before replacing.** `cerefox_get_document(section: "## Heading")`\n  returns exactly what a `replace_section` on that anchor would overwrite. Use it\n  for any section you did not write in this session. The outline gives a\n  section\'s *size*, never its *text*.\n\n- **Verify after writing** — read the result back before reporting success, and\n  report what the read actually shows.\n\n- **Partial edits cannot change a document\'s stored TITLE.** `rename_section`\n  changes a heading inside the content; the title is a separate field and still\n  needs `cerefox_ingest`.\n\n- **If a capability seems missing from one server, suspect your client first.**\n  Local and remote run the same code. **Every `cerefox_get_help()` response\n  begins with the server\'s version and the operations it registers** — you do\n  not need a special topic, and the *absence* of that block is itself an answer:\n  a server that does not print it predates v1.5.0. If that\n  disagrees with your tool list, the client is holding a list it fetched before\n  an upgrade — clients cache it at connect time. Ask the user to restart the\n  client. Do not record a capability difference between servers as a fact; every\n  such report so far has been a stale client.\n- Long inline bodies can arrive with literal `\\n`/`\\"` (the author over-escaped; Cerefox stores bytes faithfully). For long or quote-dense content, ingest from a file or build incrementally with `cerefox_insert`; read back multi-line writes.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var init_get_help_content = __esm(() => {
   HELP_SECTIONS = {
     Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `author` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part`, `author` |\n| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required), `author` |\n| `cerefox_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |\n| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete; no-op if not deleted) | `document_id` (required), `reason` (recorded in the audit log), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: \"## Heading\"` one section's text | `document_id` (required), `outline`, `section`, `section_part`, `author` |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required), `author` |\n| `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type`, `author` |\n| `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required), `author` |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `by_author` (filter), `operation`, `since`, `author` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n⚑ **Opt-in — usually absent.** The four relation tools are hidden unless the\noperator enables them (`relations_enabled`). **Trust your own tool list**: if\nthey are not in it, the feature is switched off for this deployment. That is\nnormal, not an error, and not something to work around.",
     "Editing part of a document (prefer this over re-sending)": '## Editing part of a document (prefer this over re-sending)\n\n**Re-sending a whole document to change part of it is the main way agents lose\ndata.** You have to reproduce the untouched remainder verbatim, and any drift\nsilently rewrites content nobody asked you to touch — which the caller cannot\ndiff. Use the partial-edit tools instead:\n\n1. **Learn the anchors** — `cerefox_get_document(document_id, outline: true)`.\n   Returns heading paths, per-section sizes and the `content_hash`, without the\n   body. The paths it returns are exactly what `anchor_heading` accepts.\n2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;\n   `end_of_section` adds inside a named section. It is structurally incapable of\n   removing anything, so "I meant to append" cannot become "I replaced the file".\n3. **Look before you overwrite** — `cerefox_get_document(document_id,\n   section: "## Heading")` returns exactly the text a `replace_section` on that\n   anchor would destroy. The outline gives you a section\'s *size*, never its\n   *text*, so on a document you did not write yourself this is the difference\n   between a replace and a blind overwrite.\n4. **Change or remove** → `cerefox_edit`. Put changes that belong together in\n   ONE call: they apply atomically, so a table row and the total it feeds cannot\n   end up disagreeing. To change a single line, `replace_section` on its\n   smallest enclosing heading — that is the intended granularity, not a\n   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use\n   `rename_section`: it changes the heading text and leaves the body and\n   position alone.\n5. All of them require `expected_content_hash` and **have no last-write-wins**. A\n   conflict means someone else changed the document; re-read and decide, do not\n   force it.\n\n**A section runs to the next same-or-higher heading, or to the end of the\ndocument.** So `end_of_document` inserts land inside the *last* section, and\nreplacing or deleting that section removes them too. A large shrink in the\nresponse is your warning; `cerefox_list_versions` has the previous content.\n\n**When an anchor is ambiguous the tool refuses and hands you the options** — a\nrepeated heading returns the qualifying paths, and a section with both its own\ncontent and sub-sections returns both `section_part` choices. That is a\nrecoverable answer, not a failure: retry with what it gave you.',
-    "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`** to your name on every call, reads and writes alike (e.g., "Claude Code", "archiver"). Same parameter on every tool. (`requestor` is still accepted everywhere as the pre-1.13.1 alias.) On the CLI it is `--author` on every command too (plus `--author-type` on writes); or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
+    "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`** to your name on every call, reads and writes alike (e.g., "Claude Code", "archiver"). Same parameter on every tool. (`requestor` is still accepted everywhere as the pre-1.13.1 alias.) On the CLI it is `--author` on every command too (plus `--author-type` on writes); or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **`max_bytes` has to fit a whole document.** Search returns COMPLETE documents, so a budget smaller than the top hit fits nothing. You get a header-only list saying so (never "No results found." — that means the store really has nothing). Raise `max_bytes`, or read one document with `cerefox_get_document` using `outline: true` or `section`.\n6. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n7. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n8. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document\'s `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.\n9. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n10. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n11. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n12. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n13. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
     "Update Workflow (ID-based -- preferred)": `## Update Workflow (ID-based -- preferred)
 
 \`\`\`
@@ -56449,8 +56451,23 @@ async function handler10(supabase, args, ctx) {
     project_id: projectId,
     result_count: rows.length
   });
-  if (rows.length === 0)
+  if (rows.length === 0) {
+    if (include_content && max_bytes !== null) {
+      const { data: headers } = await supabase.rpc("cerefox_metadata_search", {
+        ...params,
+        p_include_content: false,
+        p_max_bytes: null
+      });
+      const headerRows = headers ?? [];
+      if (headerRows.length > 0) {
+        return `⚠ ${headerRows.length} document(s) match, but none fit max_bytes=${max_bytes} ` + `with include_content. This is NOT an empty result. Listing them without ` + `content — raise max_bytes, or read one with cerefox_get_document ` + `(outline: true for structure).
+
+` + headerRows.map((r) => `## ${r.title} [id: ${r.document_id}]`).join(`
+`);
+      }
+    }
     return "No documents match the given criteria.";
+  }
   const showReview = await reviewWorkflowEnabled(supabase);
   const parts = rows.map((row) => {
     const projects = row.project_names?.length ? ` | projects: ${row.project_names.join(", ")}` : "";
@@ -56522,6 +56539,35 @@ var init_metadata_search = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/search.ts
+function headerLine(row) {
+  const title = row.doc_title ?? "Untitled";
+  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
+  const raw = row.best_score ?? row.score;
+  const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
+  const size = row.total_chars != null ? ` -- ${row.total_chars.toLocaleString()} chars` : "";
+  const hash = row.content_hash ? `
+hash: ${row.content_hash}` : "";
+  return `## ${title}${docId}${score}${size}${hash}`;
+}
+function degradedToHeaders(matched, maxBytes) {
+  const biggest = Math.max(...matched.map((r) => new TextEncoder().encode(JSON.stringify(r)).length));
+  const lead = `⚠ ${matched.length} result(s) matched, but none fit max_bytes=${maxBytes} ` + `(the largest is ${biggest.toLocaleString()} bytes). This is NOT an empty ` + `knowledge base. Listing what matched, without content — raise max_bytes to ` + `read it, or read one document with cerefox_get_document (outline: true for ` + `structure, or section: "## Heading" for one part).`;
+  const lines = [];
+  let used = new TextEncoder().encode(lead).length;
+  for (const row of matched) {
+    const line = headerLine(row);
+    const size = new TextEncoder().encode(line).length + 2;
+    if (used + size > maxBytes)
+      break;
+    lines.push(line);
+    used += size;
+  }
+  return lines.length > 0 ? `${lead}
+
+${lines.join(`
+
+`)}` : lead;
+}
 async function handler11(supabase, args, ctx) {
   const query = args.query;
   const project_name = args.project_name;
@@ -56596,17 +56642,22 @@ async function handler11(supabase, args, ctx) {
   const { data, error } = await supabase.rpc(rpcName, rpcParams);
   if (error)
     throw new Error(`RPC error: ${error.message}`);
-  const { accepted, truncated, usedBytes } = applyByteBudget(data ?? [], max_bytes);
+  const matched = data ?? [];
+  const { accepted, dropped, truncated, usedBytes } = applyByteBudget(matched, max_bytes);
   logUsage(supabase, {
     operation: "search",
     accessPath: ctx.accessPath,
     requestor: callerIdentity(args),
     query_text: query,
     project_id: projectId,
-    result_count: accepted.length
+    result_count: matched.length,
+    ...truncated ? { extra: { returned: accepted.length, truncated: true } } : {}
   });
-  if (accepted.length === 0)
+  if (matched.length === 0)
     return "No results found.";
+  if (accepted.length === 0) {
+    return degradedToHeaders(matched, max_bytes);
+  }
   const rows = accepted;
   const belowConfidence = rows.length > 0 && rows.every((r) => r.below_confidence === true);
   const parts = rows.map((row) => {
@@ -56634,7 +56685,7 @@ ${row.full_content ?? ""}`;
   if (truncated) {
     output += `
 
-[Results truncated at ${usedBytes} bytes. Use a more specific query or a smaller match_count to see more.]`;
+[${accepted.length} of ${matched.length} result(s) shown; truncated at ` + `${usedBytes} bytes. ${dropped.length} did not fit: ` + `${dropped.map((r) => r.doc_title ?? "Untitled").join(", ")}. ` + `Raise max_bytes, narrow the query, or lower match_count.]`;
   }
   return output;
 }
@@ -57660,7 +57711,7 @@ var require_cli_progress = __commonJS(function(exports2, module2) {
 });
 
 // src/cli/commands/sync-self-docs.ts
-import { readFileSync as readFileSync11 } from "node:fs";
+import { readFileSync as readFileSync12 } from "node:fs";
 import { basename as basename4, extname as extname5 } from "node:path";
 async function runSyncSelfDocs(options = {}) {
   const project = options.project ?? "_cerefox-self-docs";
@@ -57687,7 +57738,7 @@ async function runSyncSelfDocs(options = {}) {
   const authorType = resolveAuthorType("agent");
   const outcomes = [];
   for (const doc of docs) {
-    const content = readFileSync11(doc.path, "utf8");
+    const content = readFileSync12(doc.path, "utf8");
     const m = content.match(/^#\s+(.+)$/m);
     const title = m ? m[1].trim() : basename4(doc.path, extname5(doc.path));
     try {
@@ -70871,7 +70922,7 @@ var init_stdio2 = __esm(() => {
 });
 
 // src/server.ts
-import { existsSync as existsSync12, readFileSync as readFileSync13 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "node:fs";
 function buildServer() {
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
@@ -70925,8 +70976,8 @@ async function warnIfSchemaVersionMismatch(supabase) {
     let bundled = null;
     try {
       const assets = resolveServerAssets();
-      if (existsSync12(assets.schemaFile)) {
-        const m = readFileSync13(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE2);
+      if (existsSync13(assets.schemaFile)) {
+        const m = readFileSync14(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE2);
         bundled = m ? m[1] : null;
       }
     } catch {}
@@ -77474,9 +77525,177 @@ init_config();
 init_config();
 init_compatibility();
 init_server_assets();
-import { existsSync as existsSync10, readFileSync as readFileSync7, realpathSync, statSync as statSync2 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync8, realpathSync, statSync as statSync2 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join10 } from "node:path";
+
+// src/web/daemon.ts
+import { spawn } from "node:child_process";
+import {
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync3,
+  openSync,
+  readFileSync as readFileSync7,
+  rmSync,
+  writeFileSync as writeFileSync4
+} from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join8 } from "node:path";
+function resolveStateDir(override = process.env.CEREFOX_CONFIG_DIR, home = homedir5()) {
+  override = (override ?? "").trim();
+  if (!override)
+    return join8(home, ".cerefox");
+  return override === "~" || override.startsWith("~/") ? join8(home, override.slice(2)) : override;
+}
+var STATE_DIR = resolveStateDir();
+var PID_FILE = join8(STATE_DIR, "web.pid");
+var LOG_FILE = join8(STATE_DIR, "web.log");
+var daemonPaths = { stateDir: STATE_DIR, pidFile: PID_FILE, logFile: LOG_FILE };
+function ensureStateDir() {
+  if (!existsSync9(STATE_DIR))
+    mkdirSync3(STATE_DIR, { recursive: true });
+}
+function readPidFile() {
+  if (!existsSync9(PID_FILE))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync7(PID_FILE, "utf8"));
+    if (typeof parsed.pid !== "number")
+      return null;
+    return {
+      pid: parsed.pid,
+      port: typeof parsed.port === "number" ? parsed.port : 8000,
+      host: typeof parsed.host === "string" ? parsed.host : "127.0.0.1",
+      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "unknown"
+    };
+  } catch {
+    return null;
+  }
+}
+function writePidFile(info) {
+  ensureStateDir();
+  writeFileSync4(PID_FILE, JSON.stringify(info, null, 2) + `
+`, "utf8");
+}
+function removePidFile() {
+  rmSync(PID_FILE, { force: true });
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+async function probeVersion(host, port, timeoutMs = 1500) {
+  const probeHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+  try {
+    const ctrl = new AbortController;
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const resp = await fetch(`http://${probeHost}:${port}/api/v1/version`, {
+        signal: ctrl.signal
+      });
+      if (!resp.ok)
+        return { responding: false, version: null };
+      const body = await resp.json().catch(() => null);
+      return {
+        responding: true,
+        version: typeof body?.version === "string" ? body.version : null
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return { responding: false, version: null };
+  }
+}
+async function isResponding(host, port, timeoutMs = 1500) {
+  return (await probeVersion(host, port, timeoutMs)).responding;
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function assertUnix() {
+  if (process.platform === "win32") {
+    throw new Error("Daemon mode (`cerefox web start/stop/status`) is not supported on Windows yet. " + "Run `cerefox web` in the foreground, or set up a Windows service manually.");
+  }
+}
+async function startDaemon(opts) {
+  assertUnix();
+  ensureStateDir();
+  const existing = readPidFile();
+  if (existing && isProcessAlive(existing.pid)) {
+    return existing.port === opts.port ? { kind: "already-running", info: existing } : { kind: "port-conflict", info: existing };
+  }
+  if (existing)
+    removePidFile();
+  const logFd = openSync(LOG_FILE, "a");
+  const child = spawn(opts.runtime, [opts.scriptPath, "web", "--host", opts.host, "--port", String(opts.port)], { detached: true, stdio: ["ignore", logFd, logFd] });
+  child.unref();
+  if (typeof child.pid !== "number") {
+    throw new Error("Failed to spawn the web server process (no pid).");
+  }
+  writePidFile({
+    pid: child.pid,
+    port: opts.port,
+    host: opts.host,
+    startedAt: new Date().toISOString()
+  });
+  let responding = false;
+  for (let i = 0;i < 20; i++) {
+    if (!isProcessAlive(child.pid))
+      break;
+    if (await isResponding(opts.host, opts.port)) {
+      responding = true;
+      break;
+    }
+    await sleep2(250);
+  }
+  return { kind: "started", pid: child.pid, responding };
+}
+async function stopDaemon() {
+  assertUnix();
+  const info = readPidFile();
+  if (!info || !isProcessAlive(info.pid)) {
+    removePidFile();
+    return { kind: "not-running" };
+  }
+  try {
+    process.kill(info.pid, "SIGTERM");
+  } catch {}
+  let forced = false;
+  let alive = true;
+  for (let i = 0;i < 12; i++) {
+    await sleep2(250);
+    if (!isProcessAlive(info.pid)) {
+      alive = false;
+      break;
+    }
+  }
+  if (alive) {
+    try {
+      process.kill(info.pid, "SIGKILL");
+      forced = true;
+    } catch {}
+  }
+  removePidFile();
+  return { kind: "stopped", pid: info.pid, forced };
+}
+function restartCommand(host, port) {
+  const flags = `${host === "127.0.0.1" ? "" : ` --host ${host}`}${port === 8000 ? "" : ` --port ${port}`}`;
+  return `cerefox web stop && cerefox web start${flags}`;
+}
+async function statusDaemon() {
+  const info = readPidFile();
+  if (!info)
+    return { kind: "stopped" };
+  if (!isProcessAlive(info.pid))
+    return { kind: "stale", info };
+  const { responding, version } = await probeVersion(info.host, info.port);
+  return { kind: "running", info, responding, version };
+}
+
+// src/cli/util/checks.ts
 function checkBinary() {
   return {
     name: "binary",
@@ -77527,7 +77746,7 @@ function checkConfig() {
       hint: "Run `cerefox init` to bootstrap."
     };
   }
-  if (!existsSync10(envPath)) {
+  if (!existsSync11(envPath)) {
     const settings = loadSettings();
     if (settings.supabaseUrl && settings.supabaseKey) {
       return {
@@ -77739,9 +77958,9 @@ var SCHEMA_VERSION_RE = /^--\s*@version:\s*(\S+)/m;
 function readBundledSchemaVersion() {
   try {
     const assets = resolveServerAssets();
-    if (!existsSync10(assets.schemaFile))
+    if (!existsSync11(assets.schemaFile))
       return null;
-    const m = readFileSync7(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE);
+    const m = readFileSync8(assets.schemaFile, "utf8").match(SCHEMA_VERSION_RE);
     return m ? m[1] : null;
   } catch {
     return null;
@@ -77984,21 +78203,69 @@ async function checkMetadataHealth() {
   };
 }
 function hasCerefoxInJsonFile(path) {
-  if (!existsSync10(path))
+  if (!existsSync11(path))
     return false;
   try {
-    const parsed = JSON.parse(readFileSync7(path, "utf8"));
+    const parsed = JSON.parse(readFileSync8(path, "utf8"));
     const mcpServers = parsed.mcpServers;
     return Boolean(mcpServers && typeof mcpServers === "object" && "cerefox" in mcpServers);
   } catch {
     return false;
   }
 }
+async function checkWebDaemon() {
+  let status;
+  try {
+    status = await statusDaemon();
+  } catch {
+    return { name: "web server", status: "skipped", detail: "could not read the daemon pidfile" };
+  }
+  if (status.kind === "stopped") {
+    return { name: "web server", status: "skipped", detail: "no background daemon running" };
+  }
+  if (status.kind === "stale") {
+    return {
+      name: "web server",
+      status: "skipped",
+      detail: `no daemon running (stale pidfile for process ${status.info.pid}).`,
+      hint: "Clean it up: cerefox web stop"
+    };
+  }
+  if (!status.responding) {
+    return {
+      name: "web server",
+      status: "warn",
+      detail: `process ${status.info.pid} is alive but not answering on :${status.info.port}.`,
+      hint: `Check the log, then: ${restartCommand(status.info.host, status.info.port)}`
+    };
+  }
+  if (status.version && status.version !== PKG_VERSION) {
+    return {
+      name: "web server",
+      status: "warn",
+      detail: `running v${status.version} on :${status.info.port}, but this client is v${PKG_VERSION} ` + `— it is still serving the previous build.`,
+      hint: `Restart it: ${restartCommand(status.info.host, status.info.port)}`
+    };
+  }
+  if (!status.version) {
+    return {
+      name: "web server",
+      status: "warn",
+      detail: `responding on :${status.info.port} (pid ${status.info.pid}) but did not report a version.`,
+      hint: `Confirm it is Cerefox: curl http://${status.info.host}:${status.info.port}/api/v1/version`
+    };
+  }
+  return {
+    name: "web server",
+    status: "ok",
+    detail: `v${status.version} on :${status.info.port} (pid ${status.info.pid})`
+  };
+}
 function checkMcpConfigs() {
-  const home = homedir6();
-  const claudeCodeUser = join9(home, ".claude.json");
-  const claudeCodeProj = join9(process.cwd(), ".mcp.json");
-  const claudeDesktop = process.platform === "darwin" ? join9(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join9(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join9(home, ".config", "Claude", "claude_desktop_config.json");
+  const home = homedir7();
+  const claudeCodeUser = join10(home, ".claude.json");
+  const claudeCodeProj = join10(process.cwd(), ".mcp.json");
+  const claudeDesktop = process.platform === "darwin" ? join10(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join10(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json") : join10(home, ".config", "Claude", "claude_desktop_config.json");
   const found = [];
   if (hasCerefoxInJsonFile(claudeCodeUser))
     found.push("Claude Code (user)");
@@ -78022,8 +78289,8 @@ function checkMcpConfigs() {
 }
 function checkLegacyShadowEnv(opts = {}) {
   const activeEnv = resolveEnvFile(opts);
-  const cwdEnv = join9(opts.cwd ?? process.cwd(), ".env");
-  if (!existsSync10(activeEnv) || !existsSync10(cwdEnv))
+  const cwdEnv = join10(opts.cwd ?? process.cwd(), ".env");
+  if (!existsSync11(activeEnv) || !existsSync11(cwdEnv))
     return null;
   try {
     if (realpathSync(activeEnv) === realpathSync(cwdEnv))
@@ -78197,6 +78464,7 @@ async function runAllChecks(opts = {}) {
     { name: "metadata health", phase: "Checking metadata well-formedness", run: () => checkMetadataHealth() },
     { name: "edge functions", phase: "Probing Edge Function versions", run: () => checkEdgeFunctionsCompat() },
     { name: "postgres", phase: "Probing Postgres DDL endpoint", run: () => checkPostgres() },
+    { name: "web server", phase: "Probing the web daemon", run: () => checkWebDaemon() },
     { name: "mcp clients", phase: "Scanning MCP client configs", run: () => checkMcpConfigs() }
   ];
   return runSteps(steps, opts);
@@ -78592,11 +78860,11 @@ function registerGetDoc(program) {
 init_dist4();
 init_cli_core();
 init_config();
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { basename as basename2, extname as extname3 } from "node:path";
 
 // src/ingestion/pipeline.ts
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 import { basename, extname as extname2, resolve as resolve3 } from "node:path";
 // ../../_shared/ingest/pipeline-helpers.ts
 import { createHash } from "node:crypto";
@@ -79259,7 +79527,7 @@ class IngestionPipeline {
     };
   }
   async ingestFile(path, opts = {}) {
-    const text = await fileToMarkdown(path, readFileSync8(path));
+    const text = await fileToMarkdown(path, readFileSync9(path));
     const absPath = resolve3(path);
     const stem = basename(absPath, extname2(absPath));
     return this.ingestText({
@@ -79294,7 +79562,7 @@ async function readContent(path, paste) {
   }
   let content;
   try {
-    content = readFileSync9(path, "utf8");
+    content = readFileSync10(path, "utf8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw userError(`Cannot read ${path}: ${msg}`);
@@ -79404,14 +79672,14 @@ init_cli_core();
 init_mcp_tools();
 init_config();
 init_client();
-import { readFileSync as readFileSync10 } from "node:fs";
+import { readFileSync as readFileSync11 } from "node:fs";
 function resolveText(value, what) {
   if (value === undefined)
     throw userError(`${what} is required.`);
   if (value === "-")
-    return readFileSync10(0, "utf8");
+    return readFileSync11(0, "utf8");
   if (value.startsWith("@"))
-    return readFileSync10(value.slice(1), "utf8");
+    return readFileSync11(value.slice(1), "utf8");
   return value;
 }
 function context() {
@@ -79472,7 +79740,7 @@ init_cli_core();
 init_config();
 var import_cli_progress = __toESM(require_cli_progress(), 1);
 import { readdirSync as readdirSync4, statSync as statSync3 } from "node:fs";
-import { basename as basename3, extname as extname4, join as join10 } from "node:path";
+import { basename as basename3, extname as extname4, join as join11 } from "node:path";
 function walk(dir, extensions) {
   let entries;
   try {
@@ -79482,7 +79750,7 @@ function walk(dir, extensions) {
   }
   const files = [];
   for (const name of entries) {
-    const full = join10(dir, name);
+    const full = join11(dir, name);
     let stat;
     try {
       stat = statSync3(full);
@@ -79585,20 +79853,20 @@ import { spawnSync as spawnSync4 } from "node:child_process";
 import {
   chmodSync,
   copyFileSync as copyFileSync2,
-  existsSync as existsSync11,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync12,
-  writeFileSync as writeFileSync4
+  existsSync as existsSync12,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync13,
+  writeFileSync as writeFileSync5
 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
-import { dirname as dirname4, join as join11 } from "node:path";
+import { homedir as homedir8 } from "node:os";
+import { dirname as dirname4, join as join12 } from "node:path";
 async function readConfigFile(path) {
-  if (!existsSync11(path)) {
+  if (!existsSync12(path)) {
     throw userError(`--config file not found: ${path}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync12(path, "utf8"));
+    parsed = JSON.parse(readFileSync13(path, "utf8"));
   } catch (err) {
     throw userError(`--config: invalid JSON in ${path}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -79640,7 +79908,7 @@ function parseDotEnvFile(content) {
   return map;
 }
 function answersFromEnvFile(path) {
-  const parsed = parseDotEnvFile(readFileSync12(path, "utf8"));
+  const parsed = parseDotEnvFile(readFileSync13(path, "utf8"));
   const required = ["CEREFOX_SUPABASE_URL", "CEREFOX_SUPABASE_KEY", "OPENAI_API_KEY"];
   for (const key of required) {
     if (!parsed[key] || parsed[key].trim() === "") {
@@ -79895,8 +80163,8 @@ async function postWriteLifecycle(envPath, options) {
   println(c.dim(`  Config in effect: ${envPath}`));
 }
 function writeAnswersTo(target, answers) {
-  mkdirSync4(dirname4(target), { recursive: true });
-  writeFileSync4(target, buildEnvFile(answers), "utf8");
+  mkdirSync5(dirname4(target), { recursive: true });
+  writeFileSync5(target, buildEnvFile(answers), "utf8");
   if (process.platform !== "win32") {
     try {
       chmodSync(target, 384);
@@ -79906,12 +80174,12 @@ function writeAnswersTo(target, answers) {
   }
 }
 async function action23(options) {
-  const homeEnv = join11(homedir7(), USER_STATE_DIR_NAME, ".env");
-  const cwdEnv = join11(process.cwd(), ".env");
+  const homeEnv = join12(homedir8(), USER_STATE_DIR_NAME, ".env");
+  const cwdEnv = join12(process.cwd(), ".env");
   const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
   if (explicitDir) {
     const target = resolveEnvFile();
-    if (existsSync11(target) && !options.force) {
+    if (existsSync12(target) && !options.force) {
       println(c.yellow(`⚠ Config already exists at ${target}.`));
       const ok = await confirm("Overwrite?", true);
       if (!ok) {
@@ -79933,7 +80201,7 @@ async function action23(options) {
     await postWriteLifecycle(target, options);
     return;
   }
-  if (existsSync11(homeEnv) && !options.force) {
+  if (existsSync12(homeEnv) && !options.force) {
     println(c.yellow(`⚠ Config already exists at ${homeEnv}.`));
     const ok = await confirm("Overwrite?", true);
     if (!ok) {
@@ -79954,12 +80222,12 @@ async function action23(options) {
     await postWriteLifecycle(homeEnv, options);
     return;
   }
-  if (existsSync11(cwdEnv) && !options.force && !options.config) {
+  if (existsSync12(cwdEnv) && !options.force && !options.config) {
     printMigrationMenu(cwdEnv, homeEnv);
     const ch = await promptMigrationChoice();
     println("");
     if (ch === "c") {
-      mkdirSync4(dirname4(homeEnv), { recursive: true });
+      mkdirSync5(dirname4(homeEnv), { recursive: true });
       copyFileSync2(cwdEnv, homeEnv);
       if (process.platform !== "win32") {
         try {
@@ -80554,35 +80822,35 @@ function registerMigrateFormat(program) {
 // src/cli/commands/restore.ts
 init_cli_core();
 init_client();
-import { existsSync as existsSync13, readFileSync as readFileSync14, readdirSync as readdirSync5, statSync as statSync4 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { join as join12, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync14, readFileSync as readFileSync15, readdirSync as readdirSync5, statSync as statSync4 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
+import { join as join13, resolve as resolve4 } from "node:path";
 function expandHome2(path) {
   if (path === "~")
-    return homedir8();
+    return homedir9();
   if (path.startsWith("~/"))
-    return join12(homedir8(), path.slice(2));
+    return join13(homedir9(), path.slice(2));
   return path;
 }
 function resolveBackupFile(target) {
   const path = resolve4(expandHome2(target));
-  if (!existsSync13(path)) {
+  if (!existsSync14(path)) {
     throw userError(`Backup path not found: ${target}`);
   }
   const stat = statSync4(path);
   if (stat.isFile())
     return path;
-  const candidates = readdirSync5(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join12(path, n)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
+  const candidates = readdirSync5(path).filter((n) => n.endsWith(".json") && n.startsWith("cerefox-")).map((n) => ({ name: n, mtime: statSync4(join13(path, n)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
   if (candidates.length === 0) {
     throw userError(`No cerefox-*.json files in ${path}`);
   }
-  return join12(path, candidates[0].name);
+  return join13(path, candidates[0].name);
 }
 async function action31(target, options) {
   const file = resolveBackupFile(target);
   let payload;
   try {
-    payload = JSON.parse(readFileSync14(file, "utf8"));
+    payload = JSON.parse(readFileSync15(file, "utf8"));
   } catch (err) {
     throw userError(`Could not parse backup file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -80993,6 +81261,12 @@ async function action33(options) {
   }
   println("");
   println(c.green(`✓ Upgraded to ${target}.`));
+  const daemon = await statusDaemon().catch(() => null);
+  if (daemon?.kind === "running" && daemon.version !== target) {
+    println("");
+    println(c.yellow(`⚠ The web server is still running the previous build ` + `(pid ${daemon.info.pid} on :${daemon.info.port}` + `${daemon.version ? `, v${daemon.version}` : ""}).`));
+    println("  Restart it: " + c.bold(restartCommand(daemon.info.host, daemon.info.port)));
+  }
   println("");
   println("Next steps:");
   println("  1. " + c.bold("cerefox server deploy") + "   apply this release's schema/RPC/EF updates");
@@ -81050,7 +81324,7 @@ init_config();
 import { randomBytes } from "node:crypto";
 
 // src/cli/util/env-file.ts
-import { copyFileSync as copyFileSync3, existsSync as existsSync14, readFileSync as readFileSync15, writeFileSync as writeFileSync5 } from "node:fs";
+import { copyFileSync as copyFileSync3, existsSync as existsSync15, readFileSync as readFileSync16, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname5 } from "node:path";
 import { spawnSync as spawnSync6 } from "node:child_process";
 function escapeRegExp(s) {
@@ -81060,12 +81334,12 @@ function upsertEnvVar(path, key, value, opts = {}) {
   const line = `${key}=${value}`;
   const header = opts.comment ? `# ${opts.comment}
 ` : "";
-  if (!existsSync14(path)) {
-    writeFileSync5(path, `${header}${line}
+  if (!existsSync15(path)) {
+    writeFileSync6(path, `${header}${line}
 `, { mode: 384 });
     return { path, action: "created" };
   }
-  const original = readFileSync15(path, "utf8");
+  const original = readFileSync16(path, "utf8");
   let backupPath;
   if (!opts.noBackup) {
     backupPath = `${path}.pre-cerefox.bak`;
@@ -81086,13 +81360,13 @@ ${header}${line}
 `;
     action = "added";
   }
-  writeFileSync5(path, next);
+  writeFileSync6(path, next);
   return { path, action, backupPath };
 }
 function readEnvVar(path, key) {
-  if (!existsSync14(path))
+  if (!existsSync15(path))
     return null;
-  const m = readFileSync15(path, "utf8").match(new RegExp(`^\\s*${escapeRegExp(key)}=(.*)$`, "m"));
+  const m = readFileSync16(path, "utf8").match(new RegExp(`^\\s*${escapeRegExp(key)}=(.*)$`, "m"));
   return m ? m[1].trim() : null;
 }
 function envGitignoreWarning(path) {
@@ -81113,7 +81387,7 @@ function envGitignoreWarning(path) {
 }
 
 // src/web/auth.ts
-import { existsSync as existsSync15 } from "node:fs";
+import { existsSync as existsSync16 } from "node:fs";
 
 // ../../node_modules/.bun/@hono+node-server@2.0.12+19b9adbcbc3b652f/node_modules/@hono/node-server/dist/conninfo.mjs
 var getConnInfo = (c) => {
@@ -81178,7 +81452,7 @@ var LOOPBACK_ADDRESSES = new Set([
 ]);
 function isContainerised() {
   try {
-    return existsSync15("/.dockerenv");
+    return existsSync16("/.dockerenv");
   } catch {
     return false;
   }
@@ -82902,8 +83176,8 @@ var _baseMimes = {
 var baseMimes = _baseMimes;
 
 // ../../node_modules/.bun/@hono+node-server@2.0.12+19b9adbcbc3b652f/node_modules/@hono/node-server/dist/serve-static.mjs
-import { createReadStream, existsSync as existsSync16, statSync as statSync5 } from "node:fs";
-import { join as join13 } from "node:path";
+import { createReadStream, existsSync as existsSync17, statSync as statSync5 } from "node:fs";
+import { join as join14 } from "node:path";
 var COMPRESSIBLE_CONTENT_TYPE_REGEX = /^\s*(?:text\/[^;\s]+|application\/(?:javascript|json|xml|xml-dtd|ecmascript|dart|postscript|rtf|tar|toml|vnd\.dart|vnd\.ms-fontobject|vnd\.ms-opentype|wasm|x-httpd-php|x-javascript|x-ns-proxy-autoconfig|x-sh|x-tar|x-virtualbox-hdd|x-virtualbox-ova|x-virtualbox-ovf|x-virtualbox-vbox|x-virtualbox-vdi|x-virtualbox-vhd|x-virtualbox-vmdk|x-www-form-urlencoded)|font\/(?:otf|ttf)|image\/(?:bmp|vnd\.adobe\.photoshop|vnd\.microsoft\.icon|vnd\.ms-dds|x-icon|x-ms-bmp)|message\/rfc822|model\/gltf-binary|x-shader\/x-fragment|x-shader\/x-vertex|[^;\s]+?\+(?:json|text|xml|yaml))(?:[;\s]|$)/i;
 var ENCODINGS = {
   br: ".br",
@@ -82976,7 +83250,7 @@ var tryDecodeURI = (str) => tryDecode(str, decodeURI);
 var serveStatic = (options = { root: "" }) => {
   const root = options.root || "";
   const optionPath = options.path;
-  if (root !== "" && !existsSync16(root))
+  if (root !== "" && !existsSync17(root))
     console.error(`serveStatic: root path '${root}' is not found, are you sure it's correct?`);
   return async (c, next) => {
     if (c.finalized)
@@ -82993,11 +83267,11 @@ var serveStatic = (options = { root: "" }) => {
         await options.onNotFound?.(c.req.path, c);
         return next();
       }
-    let path = join13(root, !optionPath && options.rewriteRequestPath ? options.rewriteRequestPath(filename, c) : filename);
+    let path = join14(root, !optionPath && options.rewriteRequestPath ? options.rewriteRequestPath(filename, c) : filename);
     let stats = getStats(path);
     if (stats && stats.isDirectory()) {
       const indexFile = options.index ?? "index.html";
-      path = join13(path, indexFile);
+      path = join14(path, indexFile);
       stats = getStats(path);
     }
     if (!stats) {
@@ -83059,9 +83333,9 @@ var serveStatic = (options = { root: "" }) => {
 };
 
 // src/web/server.ts
-import { existsSync as existsSync20 } from "node:fs";
-import { readFileSync as readFileSync18 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync21 } from "node:fs";
+import { readFileSync as readFileSync19, statSync as statSync8 } from "node:fs";
+import { join as join18 } from "node:path";
 
 // ../../node_modules/.bun/hono@4.12.34/node_modules/hono/dist/compose.js
 var compose = (middleware, onError, onNotFound) => {
@@ -84781,7 +85055,7 @@ function registerAuditUsageRoutes(app, ctx) {
 }
 
 // src/web/routes/config.ts
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 import { sep } from "node:path";
 init_config();
 
@@ -84902,7 +85176,7 @@ function registerConfigRoutes(app, ctx) {
     let configFile = null;
     try {
       const abs = resolveEnvFile();
-      const home = homedir9();
+      const home = homedir10();
       configFile = abs === home || abs.startsWith(home + sep) ? `~${abs.slice(home.length)}` : abs;
     } catch {}
     return c.json({ keys: entries, config_file: configFile });
@@ -86234,12 +86508,12 @@ import { execFileSync } from "node:child_process";
 
 // src/web/docs.ts
 import {
-  existsSync as existsSync17,
-  readFileSync as readFileSync16,
+  existsSync as existsSync18,
+  readFileSync as readFileSync17,
   readdirSync as readdirSync6,
   statSync as statSync6
 } from "node:fs";
-import { basename as basename5, dirname as dirname6, join as join14, resolve as resolve5 } from "node:path";
+import { basename as basename5, dirname as dirname6, join as join15, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var TOP_LEVEL_DOCS = [
   { filename: "README.md", path: "README.md", category: "readme" },
@@ -86260,32 +86534,32 @@ function moduleDir2() {
 function resolveDocsRoots() {
   const here = moduleDir2();
   const pkgRootCandidates = [
-    join14(here, "..", ".."),
-    join14(here, "..", "..", "..", "..")
+    join15(here, "..", ".."),
+    join15(here, "..", "..", "..", "..")
   ];
   let pkgGuides = null;
   let pkgTopLevel = null;
   for (const pkg of pkgRootCandidates) {
-    const guides = join14(pkg, "docs", "guides");
-    if (existsSync17(guides) && statSync6(guides).isDirectory()) {
+    const guides = join15(pkg, "docs", "guides");
+    if (existsSync18(guides) && statSync6(guides).isDirectory()) {
       pkgGuides = guides;
       pkgTopLevel = pkg;
       break;
     }
   }
-  const repoCandidate = join14(here, "..", "..", "..", "..");
-  const repoGuides = join14(repoCandidate, "docs", "guides");
+  const repoCandidate = join15(here, "..", "..", "..", "..");
+  const repoGuides = join15(repoCandidate, "docs", "guides");
   const repoTopLevel = repoCandidate;
   return {
     pkgGuides,
     pkgTopLevel,
-    repoGuides: existsSync17(repoGuides) ? repoGuides : null,
-    repoTopLevel: existsSync17(join14(repoTopLevel, "README.md")) ? repoTopLevel : null
+    repoGuides: existsSync18(repoGuides) ? repoGuides : null,
+    repoTopLevel: existsSync18(join15(repoTopLevel, "README.md")) ? repoTopLevel : null
   };
 }
 function readH1(filePath) {
   try {
-    const content = readFileSync16(filePath, "utf8");
+    const content = readFileSync17(filePath, "utf8");
     const match = content.match(/^#\s+(.+?)\s*$/m);
     return match ? match[1] : null;
   } catch {
@@ -86305,8 +86579,8 @@ function listBundledDocs2() {
   const topRoot = pkgTopLevel ?? repoTopLevel;
   if (topRoot) {
     for (const t of TOP_LEVEL_DOCS) {
-      const abs = join14(topRoot, t.filename);
-      if (existsSync17(abs)) {
+      const abs = join15(topRoot, t.filename);
+      if (existsSync18(abs)) {
         entries.push(entryForFile(abs, t.path, t.category));
       }
     }
@@ -86315,7 +86589,7 @@ function listBundledDocs2() {
   if (guidesRoot) {
     const names = readdirSync6(guidesRoot).filter((n) => n.endsWith(".md")).sort();
     for (const name of names) {
-      const abs = join14(guidesRoot, name);
+      const abs = join15(guidesRoot, name);
       entries.push(entryForFile(abs, `guides/${name}`, "guide"));
     }
   }
@@ -86333,9 +86607,9 @@ function readDoc(docPath) {
   if (!candidate.startsWith(rootResolved + "/") && candidate !== rootResolved) {
     return null;
   }
-  if (existsSync17(candidate) && statSync6(candidate).isFile()) {
+  if (existsSync18(candidate) && statSync6(candidate).isFile()) {
     try {
-      return readFileSync16(candidate, "utf8");
+      return readFileSync17(candidate, "utf8");
     } catch {
       return null;
     }
@@ -86490,17 +86764,17 @@ function registerPostgrestProxy(app) {
 
 // src/web/routes/preferences.ts
 init_config();
-import { existsSync as existsSync18, mkdirSync as mkdirSync5, readFileSync as readFileSync17, writeFileSync as writeFileSync6 } from "node:fs";
-import { join as join15 } from "node:path";
+import { existsSync as existsSync19, mkdirSync as mkdirSync6, readFileSync as readFileSync18, writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join16 } from "node:path";
 function isTheme(v) {
   return v === "auto" || v === "light" || v === "dark";
 }
 function prefsFile() {
-  return join15(userStateDir(), "web-prefs.json");
+  return join16(userStateDir(), "web-prefs.json");
 }
 function readPrefs() {
   try {
-    const raw = JSON.parse(readFileSync17(prefsFile(), "utf8"));
+    const raw = JSON.parse(readFileSync18(prefsFile(), "utf8"));
     if (isTheme(raw.theme))
       return { theme: raw.theme };
   } catch {}
@@ -86516,9 +86790,9 @@ function registerPreferencesRoutes(app) {
     const next = { ...readPrefs(), theme: body.theme };
     try {
       const dir = userStateDir();
-      if (!existsSync18(dir))
-        mkdirSync5(dir, { recursive: true });
-      writeFileSync6(prefsFile(), `${JSON.stringify(next, null, 2)}
+      if (!existsSync19(dir))
+        mkdirSync6(dir, { recursive: true });
+      writeFileSync7(prefsFile(), `${JSON.stringify(next, null, 2)}
 `);
     } catch (err) {
       return c.json({ detail: err instanceof Error ? err.message : String(err) }, 500);
@@ -86653,21 +86927,21 @@ function registerProjectsRoutes(app, ctx) {
 }
 
 // src/web/static.ts
-import { existsSync as existsSync19, statSync as statSync7 } from "node:fs";
-import { dirname as dirname7, join as join16 } from "node:path";
+import { existsSync as existsSync20, statSync as statSync7 } from "node:fs";
+import { dirname as dirname7, join as join17 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function moduleDir3() {
   return dirname7(fileURLToPath4(import.meta.url));
 }
 function isUsableSpaDir(dir) {
-  return existsSync19(dir) && statSync7(dir).isDirectory() && existsSync19(join16(dir, "index.html"));
+  return existsSync20(dir) && statSync7(dir).isDirectory() && existsSync20(join17(dir, "index.html"));
 }
 function resolveSpaDist() {
   const here = moduleDir3();
   const candidates = [
-    join16(here, "..", "frontend"),
-    join16(here, "..", "..", "..", "..", "frontend", "dist"),
-    join16(here, "..", "..", "dist", "frontend")
+    join17(here, "..", "frontend"),
+    join17(here, "..", "..", "..", "..", "frontend", "dist"),
+    join17(here, "..", "..", "dist", "frontend")
   ];
   for (const c of candidates) {
     if (isUsableSpaDir(c))
@@ -86678,11 +86952,11 @@ function resolveSpaDist() {
 function resolveStaticDir() {
   const here = moduleDir3();
   const candidates = [
-    join16(here, "..", "static"),
-    join16(here, "..", "..", "..", "..", "web", "static")
+    join17(here, "..", "static"),
+    join17(here, "..", "..", "..", "..", "web", "static")
   ];
   for (const c of candidates) {
-    if (existsSync19(c) && statSync7(c).isDirectory())
+    if (existsSync20(c) && statSync7(c).isDirectory())
       return c;
   }
   return null;
@@ -86772,10 +87046,27 @@ function buildApp(ctx = buildWebContext()) {
       root: spaDist,
       rewriteRequestPath: (path) => path.replace(/^\/app/, "") || "/"
     }));
-    const indexPath = join17(spaDist, "index.html");
-    if (existsSync20(indexPath)) {
-      const indexHtml = readFileSync18(indexPath, "utf8");
-      app.get("/app/*", (c) => c.html(indexHtml));
+    app.get("/app/assets/*", (c) => c.text("Not found", 404));
+    const indexPath = join18(spaDist, "index.html");
+    if (existsSync21(indexPath)) {
+      let cached = null;
+      const readIndex = () => {
+        try {
+          const { mtimeMs, size } = statSync8(indexPath);
+          if (!cached || cached.mtimeMs !== mtimeMs || cached.size !== size) {
+            cached = { mtimeMs, size, html: readFileSync19(indexPath, "utf8") };
+          }
+        } catch {}
+        return cached?.html ?? null;
+      };
+      readIndex();
+      app.get("/app/*", (c) => {
+        const html = readIndex();
+        if (html === null) {
+          return c.text("The web UI could not be read from disk. Restart the server.", 503);
+        }
+        return c.html(html);
+      });
     }
   }
   app.get("/", (c) => c.html(ROOT_REDIRECT_HTML));
@@ -86840,160 +87131,8 @@ async function buildWebServer(options = {}) {
   };
 }
 
-// src/web/daemon.ts
-import { spawn } from "node:child_process";
-import {
-  existsSync as existsSync21,
-  mkdirSync as mkdirSync6,
-  openSync,
-  readFileSync as readFileSync19,
-  rmSync,
-  writeFileSync as writeFileSync7
-} from "node:fs";
-import { homedir as homedir10 } from "node:os";
-import { join as join18 } from "node:path";
-function resolveStateDir(override = process.env.CEREFOX_CONFIG_DIR, home = homedir10()) {
-  override = (override ?? "").trim();
-  if (!override)
-    return join18(home, ".cerefox");
-  return override === "~" || override.startsWith("~/") ? join18(home, override.slice(2)) : override;
-}
-var STATE_DIR = resolveStateDir();
-var PID_FILE = join18(STATE_DIR, "web.pid");
-var LOG_FILE = join18(STATE_DIR, "web.log");
-var daemonPaths = { stateDir: STATE_DIR, pidFile: PID_FILE, logFile: LOG_FILE };
-function ensureStateDir() {
-  if (!existsSync21(STATE_DIR))
-    mkdirSync6(STATE_DIR, { recursive: true });
-}
-function readPidFile() {
-  if (!existsSync21(PID_FILE))
-    return null;
-  try {
-    const parsed = JSON.parse(readFileSync19(PID_FILE, "utf8"));
-    if (typeof parsed.pid !== "number")
-      return null;
-    return {
-      pid: parsed.pid,
-      port: typeof parsed.port === "number" ? parsed.port : 8000,
-      host: typeof parsed.host === "string" ? parsed.host : "127.0.0.1",
-      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "unknown"
-    };
-  } catch {
-    return null;
-  }
-}
-function writePidFile(info) {
-  ensureStateDir();
-  writeFileSync7(PID_FILE, JSON.stringify(info, null, 2) + `
-`, "utf8");
-}
-function removePidFile() {
-  rmSync(PID_FILE, { force: true });
-}
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
-  }
-}
-async function isResponding(host, port, timeoutMs = 1500) {
-  const probeHost = host === "0.0.0.0" ? "127.0.0.1" : host;
-  try {
-    const ctrl = new AbortController;
-    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-    try {
-      const resp = await fetch(`http://${probeHost}:${port}/api/v1/version`, {
-        signal: ctrl.signal
-      });
-      return resp.ok;
-    } finally {
-      clearTimeout(timer);
-    }
-  } catch {
-    return false;
-  }
-}
-var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
-function assertUnix() {
-  if (process.platform === "win32") {
-    throw new Error("Daemon mode (`cerefox web start/stop/status`) is not supported on Windows yet. " + "Run `cerefox web` in the foreground, or set up a Windows service manually.");
-  }
-}
-async function startDaemon(opts) {
-  assertUnix();
-  ensureStateDir();
-  const existing = readPidFile();
-  if (existing && isProcessAlive(existing.pid)) {
-    return existing.port === opts.port ? { kind: "already-running", info: existing } : { kind: "port-conflict", info: existing };
-  }
-  if (existing)
-    removePidFile();
-  const logFd = openSync(LOG_FILE, "a");
-  const child = spawn(opts.runtime, [opts.scriptPath, "web", "--host", opts.host, "--port", String(opts.port)], { detached: true, stdio: ["ignore", logFd, logFd] });
-  child.unref();
-  if (typeof child.pid !== "number") {
-    throw new Error("Failed to spawn the web server process (no pid).");
-  }
-  writePidFile({
-    pid: child.pid,
-    port: opts.port,
-    host: opts.host,
-    startedAt: new Date().toISOString()
-  });
-  let responding = false;
-  for (let i = 0;i < 20; i++) {
-    if (!isProcessAlive(child.pid))
-      break;
-    if (await isResponding(opts.host, opts.port)) {
-      responding = true;
-      break;
-    }
-    await sleep2(250);
-  }
-  return { kind: "started", pid: child.pid, responding };
-}
-async function stopDaemon() {
-  assertUnix();
-  const info = readPidFile();
-  if (!info || !isProcessAlive(info.pid)) {
-    removePidFile();
-    return { kind: "not-running" };
-  }
-  try {
-    process.kill(info.pid, "SIGTERM");
-  } catch {}
-  let forced = false;
-  let alive = true;
-  for (let i = 0;i < 12; i++) {
-    await sleep2(250);
-    if (!isProcessAlive(info.pid)) {
-      alive = false;
-      break;
-    }
-  }
-  if (alive) {
-    try {
-      process.kill(info.pid, "SIGKILL");
-      forced = true;
-    } catch {}
-  }
-  removePidFile();
-  return { kind: "stopped", pid: info.pid, forced };
-}
-async function statusDaemon() {
-  const info = readPidFile();
-  if (!info)
-    return { kind: "stopped" };
-  if (!isProcessAlive(info.pid))
-    return { kind: "stale", info };
-  const responding = await isResponding(info.host, info.port);
-  return { kind: "running", info, responding };
-}
-
 // src/cli/commands/web.ts
+init_meta();
 function parsePort(raw) {
   const port = Number.parseInt(raw, 10);
   if (!Number.isFinite(port) || port < 1 || port > 65535) {
@@ -87113,6 +87252,10 @@ Full log: ${daemonPaths.logFile}`);
         case "running":
           if (status.responding) {
             println(c.green(`Cerefox web: running on :${status.info.port} (pid ${status.info.pid}, since ${status.info.startedAt}).`));
+            if (status.version && status.version !== PKG_VERSION) {
+              println(c.yellow(`  ⚠ It is serving v${status.version}; this CLI is v${PKG_VERSION}.`));
+              println(c.dim("  Restart to pick up the new build: " + restartCommand(status.info.host, status.info.port)));
+            }
           } else {
             println(c.yellow(`Cerefox web: process ${status.info.pid} alive but not responding on :${status.info.port}.`));
             println(c.dim(`  Check the log: ${daemonPaths.logFile}`));