loopctl-mcp-server 2.70.0 → 2.72.0

package/README.md

@@ -267,7 +267,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`. |
 | `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence`, `confidence`. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). RESERVED TAG NAMESPACE: a tag starting with `idem-` must be `idem-<family>-<digest>` (digest = 12 or 40 lowercase hex chars, e.g. `idem-url-7ebe1ca33431`) or the write is rejected 422 — never silently rewritten; put topics outside that prefix and use `idempotency_key` for idempotent capture. Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
-| `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (reversible + audited); visibility-scoped, so another agent's private/owner memory 404s. The reserved `idem-` tag namespace applies here too (see `knowledge_create`). Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
+| `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (non-destructive + audited; the in-place edit overwrites the prior body, so it is not reversible either); visibility-scoped, so another agent's private/owner memory 404s. The reserved `idem-` tag namespace applies here too (see `knowledge_create`). Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
 
@@ -299,12 +299,12 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_bulk_publish` | **Requires `LOOPCTL_USER_KEY`.** Publish drafts, partial-success style: every valid draft publishes; others are reported per-id as `skipped` (already published — idempotent — or archived/superseded), `not_found`, or `errored`. No 100-id cap (auto-chunked); duplicates ignored; safe to retry. `meta.count` = published; `meta.counts`/`meta.results` give the breakdown. Required: `article_ids` (array). |
 | `knowledge_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert a published article back to draft (hidden from search/context, not deleted). Required: `article_id`. |
 | `knowledge_bulk_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert published articles to draft in bulk, partial-success style (mirror of `knowledge_bulk_publish`): per-id `unpublished`/`skipped` (already draft, or archived/superseded)/`not_found`/`errored`. No 100-id cap (auto-chunked, ≤5000); duplicates ignored; safe to retry. Not deleted (re-publish to restore; `knowledge_bulk_delete` to archive). `meta.count`/`meta.counts`/`meta.results` give the breakdown. Required: `article_ids` (array). |
-| `knowledge_archive` | Soft-delete an article (draft or published). Row retained for audit; hidden from all reads (reversible — re-publish/edit it back). Agent role — KB-content curation, visibility-scoped (another agent's private/owner memory 404s). Required: `article_id`. |
-| `knowledge_delete` | Alias for `knowledge_archive` — DELETE verb on the REST API archives under the hood (soft delete, reversible, audited). Agent role. (Irreversible HARD delete is `knowledge_bulk_delete hard:true`, which stays `LOOPCTL_USER_KEY`.) Required: `article_id`. |
-| `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default, reversible) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
+| `knowledge_archive` | Soft-delete an article (draft or published). Row retained for audit; hidden from all reads. **NOT reversible by you** — `:archived` is a TERMINAL status (no unarchive call, no outbound transition), so restoring one needs a user-role PATCH with an explicit status. Nothing is destroyed, but do not reach for this as an undoable action: for a retraction you can undo, use `knowledge_unpublish` and `knowledge_publish`. Agent role — KB-content curation, visibility-scoped (another agent's private/owner memory 404s). Required: `article_id`. |
+| `knowledge_delete` | Alias for `knowledge_archive` — DELETE verb on the REST API archives under the hood (soft delete: row retained and audited, but NOT reversible by any call you can make, since `:archived` is terminal — use `knowledge_unpublish` when you need an undoable retraction). Agent role. (Irreversible HARD delete is `knowledge_bulk_delete hard:true`, which stays `LOOPCTL_USER_KEY`.) Required: `article_id`. |
+| `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default — non-destructive, but NOT reversible by any call: `:archived` is terminal and restoring needs a user-role PATCH) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |
-| `knowledge_consolidation` | Read the nightly consolidation ("dream") report: NUMBERED proposals for reconciling the corpus, each naming the articles involved and quoting an excerpt from each as evidence. **REPORT ONLY** — the pass writes no articles, links or conflict resolutions; every proposal is `pending` and this tool applies nothing. Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, or idempotency keys that collide under the same normalization while differing verbatim — capture tag-format drift, which the novelty gate does not catch because novelty scoring and idempotency are separate paths), `contradiction_candidate` (a SYSTEM-flagged `potential_conflict` pair of PUBLISHED articles with no recorded verdict — record one with `knowledge_resolve_conflict`, which accepts exactly these pairs), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation), `stale_entry`. **Denominators:** `corpus_size` = PUBLISHED articles owned by the tenant at scan time, not its total article count; `proposal_count` = the TRUE pre-cap count of PROPOSALS, not of articles (one duplicate group of three articles is ONE proposal, and one article can appear in proposals of several classes); `persisted_count` = proposal ROWS the report carries, lower than `proposal_count` exactly when a class hit `max_per_class` (`truncated` flags which); `meta.total_count` counts persisted proposals matching the `class` filter, so it is bounded by `persisted_count`, never `proposal_count`. `review_status`/`reviewed_by`/`reviewed_at` reset to pending/null whenever the nightly pass re-derives a proposal — refreshed machine output never inherits an approval. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
+| `knowledge_consolidation` | Read the nightly consolidation ("dream") report: NUMBERED proposals for reconciling the corpus, each naming the articles involved and quoting an excerpt from each as evidence. **This tool** applies nothing and recomputes nothing — it returns persisted rows. **The pass** it reports on does write: since #608 the nightly run UNPUBLISHES the losers of each `duplicate_capture` group that two consecutive reports both propose (consecutive meaning the previous report is at most 2 days older, so one skipped nightly run is tolerated and a longer outage is not). That is its only write to `articles`, it is an unpublish and never an archive (archive is terminal for an article), and it still writes no links or conflict resolutions. Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, or idempotency keys that collide under the same normalization while differing verbatim — capture tag-format drift, which the novelty gate does not catch because novelty scoring and idempotency are separate paths), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation). Two classes are **RETIRED** (#605) and no longer produced, though the `class` filter still accepts them so historical reports stay readable: `contradiction_candidate` (the nightly lint judges those pairs itself now) and `stale_entry` (age is not a defect signal — for stale articles call `knowledge_lint`, which computes them with a caller-chosen `stale_days`). **Denominators:** `corpus_size` = PUBLISHED articles owned by the tenant at scan time, not its total article count; `proposal_count` = the TRUE pre-cap count of PROPOSALS, not of articles (one duplicate group of three articles is ONE proposal, and one article can appear in proposals of several classes); `persisted_count` = proposal ROWS the report carries, lower than `proposal_count` exactly when a class hit `max_per_class` (`truncated` flags which); `meta.total_count` counts persisted proposals matching the `class` filter, so it is bounded by `persisted_count`, never `proposal_count`. `review_status`/`reviewed_by`/`reviewed_at` are vestigial — nothing reads them to decide anything, there is no approve/reject surface and there will not be one (#605 supersedes #594); auto-apply is gated on reversibility and two-run agreement. They still reset to pending/null whenever the nightly pass re-derives a proposal, so refreshed machine output never inherits an earlier verdict. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
 | `knowledge_export` | Export all knowledge articles as an OKF v0.1 bundle (gzipped tar archive, unbounded, bounded-memory streaming, fail-closed). Returns a curl command for direct download — **the download requires `LOOPCTL_USER_KEY`** (an orchestrator key would 403). Pass `format=json` for buffered in-memory JSON (convenience tool for file writers; capped at `export_max_buffered_export_articles` — returns 413 if over-cap). Optional: `project_id`, `format` (`tar.gz` default or `json`). |
 | `knowledge_ingest` | Submit a URL or raw content for knowledge extraction. Enqueues an Oban job. Extracted articles are **drafts by default** (lower-trust LLM output); pass `publish: true` to publish on extraction. **BYO:** runs on the tenant's own Anthropic key — a keyless tenant gets a 422 whose result leads with an `ACTION REQUIRED` notice pointing at `set_llm_config` (see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)). Required: `source_type`. One of: `url` or `content`. Optional: `project_id`, `publish`. |
 | `knowledge_ingest_batch` | Submit up to 50 ingestion items in a single request. Each item has the same shape as `knowledge_ingest` (incl. `publish`). Returns per-item results. Required: `items`. Optional: batch-level `project_id` / `publish` defaults. |

package/index.js

@@ -1786,8 +1786,9 @@ async function knowledgeUnpublish({ article_id }) {
   return toContent(result);
 }
 
-// #331: single-article archive is agent-role KB curation (reversible soft delete,
-// audited, visibility-scoped server-side).
+// #331: single-article archive is agent-role KB curation (non-destructive soft delete,
+// audited, visibility-scoped server-side). NOT reversible in code — #606/#605: `:archived`
+// is a terminal status. The row survives; nothing automated brings it back.
 async function knowledgeArchive({ article_id }) {
   const result = await apiCall(
     "POST",
@@ -1941,12 +1942,16 @@ async function knowledgeConsolidation({ day, class: klass, limit, offset } = {})
   return toContent(result);
 }
 
-async function knowledgeIngest({ url, content, source_type, project_id, publish }) {
+async function knowledgeIngest({ url, content, source_type, project_id, publish, metadata }) {
   const body = { source_type };
   if (url) body.url = url;
   if (content) body.content = content;
   if (project_id) body.project_id = project_id;
   if (publish) body.publish = true;
+  // Forwarded so `metadata.source_ref` is reachable at all: the server honours it as the
+  // source that article titles are qualified with, and declaring it in the schema above
+  // without forwarding it here would advertise a parameter that silently does nothing.
+  if (metadata && typeof metadata === "object") body.metadata = metadata;
   const result = await apiCall("POST", "/api/v1/knowledge/ingest", body, process.env.LOOPCTL_ORCH_KEY);
   // A keyless tenant gets a 422 (code no_api_key) carrying a remediation — surface it
   // prominently so a first-time agent knows to call set_llm_config before ingesting.
@@ -4817,7 +4822,9 @@ const TOOLS = [
       "project CLAUDE.mds and cross-links). Send only the fields you want to change; every " +
       "field is optional except article_id. `tags` REPLACES the whole array (send the full " +
       "desired set, not a delta). A changed body/tags re-triggers embedding + auto-linking. " +
-      "Agent role — this is KB-content curation (reversible + audited). Visibility-scoped: " +
+      "Agent role — this is KB-content curation (non-destructive + audited: the edit is in " +
+      "place and there is no version-restore endpoint, but the prior body is retained in the " +
+      "article.updated audit entry). Visibility-scoped: " +
       "you can only edit an article you can see, so another agent's private/owner memory " +
       "returns 404. `tenant_id` is never accepted. Returns the full updated article. To " +
       "instead retire/replace an article, use knowledge_archive or knowledge_resolve_conflict.",
@@ -5201,11 +5208,15 @@ const TOOLS = [
   {
     name: "knowledge_archive",
     description:
-      "Archive an article (soft delete). The article is hidden from search, context, " +
-      "and the index but the row is retained for audit/history (reversible — re-publish " +
-      "or edit it back). Works for drafts and published articles. Agent role — KB-content " +
-      "curation. Visibility-scoped: you can only archive an article you can see, so " +
-      "another agent's private/owner memory returns 404.",
+      "Archive an article (soft delete). The article is hidden from search, context, and " +
+      "the index but the row is retained for audit/history. NOT reversible by you: " +
+      "`:archived` is a TERMINAL article status — there is no unarchive call and no " +
+      "{archived -> anything} transition, so restoring one needs a user-role PATCH with an " +
+      "explicit status. Nothing is destroyed, but do not reach for this as an undoable " +
+      "action. If you want a RETRACTION you can undo, use knowledge_unpublish (published " +
+      "-> draft) and knowledge_publish to put it back. Works for drafts and published " +
+      "articles. Agent role — KB-content curation. Visibility-scoped: you can only archive " +
+      "an article you can see, so another agent's private/owner memory returns 404.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5221,10 +5232,13 @@ const TOOLS = [
     name: "knowledge_delete",
     description:
       "Delete an article. Under the hood this performs the same soft-delete (archive) " +
-      "as knowledge_archive — use whichever name is clearer at the call site. The row " +
-      "is retained for audit; there is no hard delete (that is knowledge_bulk_delete " +
-      "hard:true, which stays user-gated). Agent role — KB-content curation, reversible + " +
-      "audited, visibility-scoped (another agent's private/owner memory 404s).",
+      "as knowledge_archive — use whichever name is clearer at the call site, and note " +
+      "that it inherits archive's terminality: the row is retained for audit, but " +
+      "`:archived` has no outbound transition, so NOTHING you can call restores it. " +
+      "For a retraction you can undo, use knowledge_unpublish instead. There is no hard " +
+      "delete here (that is knowledge_bulk_delete hard:true, which stays user-gated). " +
+      "Agent role — KB-content curation: non-destructive + audited, visibility-scoped " +
+      "(another agent's private/owner memory 404s).",
     inputSchema: {
       type: "object",
       properties: {
@@ -5239,7 +5253,9 @@ const TOOLS = [
   {
     name: "knowledge_bulk_delete",
     description:
-      "Bulk archive (default, reversible) or IRREVERSIBLE hard-delete of articles by selector. " +
+      "Bulk archive (default, non-destructive but NOT reversible by any call you can make — " +
+      "`:archived` is terminal; restoring needs a user-role PATCH) or IRREVERSIBLE hard-delete " +
+      "of articles by selector. " +
       "REQUIRES LOOPCTL_USER_KEY (user role — orchestrator is NOT sufficient). Provide EXACTLY ONE " +
       "selector: article_ids (explicit list), source_type + source_id (every active article from " +
       "that source), or tag + confirm:true (every active article carrying the tag — high blast " +
@@ -5285,8 +5301,9 @@ const TOOLS = [
         hard: {
           type: "boolean",
           description:
-            "IRREVERSIBLE hard delete (vs default reversible archive). Run dry_run first to get a " +
-            "token, then pass hard:true + token.",
+            "IRREVERSIBLE hard delete (vs the default soft archive, which is non-destructive but " +
+            "terminal — `:archived` has no outbound transition, so restoring one needs a user-role " +
+            "PATCH). Run dry_run first to get a token, then pass hard:true + token.",
         },
         token: {
           type: "string",
@@ -5477,16 +5494,23 @@ const TOOLS = [
     description:
       "Read the nightly consolidation (\"dream\") report: NUMBERED proposals for reconciling " +
       "the corpus, each naming the articles involved and quoting an excerpt from each as " +
-      "evidence. REPORT ONLY — the pass writes no articles, links or conflict resolutions, " +
-      "every proposal is `pending`, and this tool applies nothing. Requires orchestrator role.\n\n" +
+      "evidence. THIS TOOL applies nothing and recomputes nothing — it returns persisted rows. " +
+      "The PASS it reports on does write: since #608 the nightly run UNPUBLISHES the losers of " +
+      "each `duplicate_capture` group that two consecutive reports both propose — consecutive " +
+      "meaning the previous report is at most 2 days older, so ONE skipped nightly run is " +
+      "tolerated and a longer outage is not. That is its " +
+      "only write to articles, it is an unpublish and never an archive (archive is terminal for " +
+      "an article), and it still writes no links or conflict resolutions. Requires orchestrator " +
+      "role.\n\n" +
       "Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, " +
       "or idempotency keys that collide under the same normalization while differing verbatim — " +
       "capture tag-format drift, which the novelty gate does not catch because novelty scoring " +
-      "and idempotency are separate paths); `contradiction_candidate` (a SYSTEM-flagged " +
-      "potential_conflict pair of PUBLISHED articles with no recorded verdict — record one via " +
-      "knowledge_resolve_conflict, which accepts exactly these pairs; this report writes " +
-      "none); `generic_title` (a placeholder title that collides on active-title uniqueness and " +
-      "blocks hub creation); `stale_entry` (past the lint staleness threshold, never reconciled).\n\n" +
+      "and idempotency are separate paths); `generic_title` (a placeholder title that collides " +
+      "on active-title uniqueness and blocks hub creation). Two classes are RETIRED (#605) and " +
+      "no longer produced, though the `class` filter still accepts them so historical reports " +
+      "stay readable: `contradiction_candidate` (the nightly lint judges those pairs itself now) " +
+      "and `stale_entry` (age is not a defect signal — for stale articles call knowledge_lint, " +
+      "which computes them with a caller-chosen `stale_days`).\n\n" +
       "Denominators: `corpus_size` counts PUBLISHED articles owned by the tenant at scan time, " +
       "not its total article count. `proposal_count` is the TRUE pre-cap count of PROPOSALS, not " +
       "of articles — one duplicate group of three articles is ONE proposal, and one article can " +
@@ -5494,8 +5518,11 @@ const TOOLS = [
       "report carries, lower than `proposal_count` exactly when a class hit `max_per_class` " +
       "(`truncated` flags which). `meta.total_count` counts persisted proposals matching the " +
       "`class` filter, so it is bounded by `persisted_count`, never by `proposal_count`.\n\n" +
-      "Review state (`review_status`/`reviewed_by`/`reviewed_at`) RESETS to pending/null whenever " +
-      "the nightly pass re-derives a proposal: refreshed machine output never inherits an approval.",
+      "Review state (`review_status`/`reviewed_by`/`reviewed_at`) is VESTIGIAL: nothing reads it " +
+      "to decide anything, there is no approve/reject surface and there will not be one (#605 " +
+      "supersedes #594) — auto-apply is gated on reversibility and two-run agreement, not on an " +
+      "approval. It still RESETS to pending/null whenever the nightly pass re-derives a proposal, " +
+      "so refreshed machine output can never inherit an earlier verdict.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5644,6 +5671,25 @@ const TOOLS = [
           description:
             "Optional: publish extracted articles immediately instead of staging them as drafts (default false).",
         },
+        metadata: {
+          type: "object",
+          description:
+            "Optional metadata map. `source_ref` is the one key with behaviour: it names the " +
+            "SPECIFIC source (a URL, repo, or document name) and is what lets extracted article " +
+            "titles qualify themselves — without it a CHANGELOG file can only become an article " +
+            "titled \"Changelog\", which is indistinguishable from every other document's " +
+            "changelog once it is in the corpus. It overrides the name derived from `url`, and " +
+            "is the ONLY way to name the source of an inline `content` ingest. Its value is " +
+            "included in the extraction prompt POSTed to the tenant's LLM provider (reduced the " +
+            "same way a url is: userinfo and query string stripped, host and path kept). Omit it " +
+            "rather than passing a placeholder — a model will qualify a title WITH it.",
+          properties: {
+            source_ref: {
+              type: "string",
+              description: "The specific source that article titles are qualified with.",
+            },
+          },
+        },
       },
       required: ["source_type"],
     },
@@ -5689,7 +5735,19 @@ const TOOLS = [
               },
               metadata: {
                 type: "object",
-                description: "Optional metadata map.",
+                description:
+                  "Optional metadata map. Set `source_ref` to the SPECIFIC source (URL, repo, " +
+                  "or document name) so extracted titles qualify themselves — without it a " +
+                  "CHANGELOG becomes an article titled \"Changelog\", indistinguishable from " +
+                  "every other document's changelog in the corpus. Overrides the url-derived " +
+                  "name, and is the only way to name an inline `content` item. Sent to the " +
+                  "LLM provider in the extraction prompt. Omit rather than passing a placeholder.",
+                properties: {
+                  source_ref: {
+                    type: "string",
+                    description: "The specific source that article titles are qualified with.",
+                  },
+                },
               },
             },
             required: ["source_type"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.70.0",
+  "version": "2.72.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",