> ## Documentation Index
> Fetch the complete documentation index at: https://docs.the40thieves.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> The tool surface reliquary-tc exposes to MCP clients, and the facade that shapes it.

reliquary-tc groups **its tools across modules M1–M8 plus admin**. Every tool has
a Zod-validated input schema, a structured result, a declared scope set, and a
scope class that selects its rate-limit tier. `tools/list` also derives MCP
**annotations** (`readOnlyHint` / `destructiveHint` / `openWorldHint`) and a
`title` from registry ground truth, and a tool may carry an optional `outputSchema`
and `icons`. Advertised schemas are **JSON Schema 2020-12** (the MCP `2025-11-25`
default dialect), matching the negotiated protocol version, and lowered to the
subset every client accepts (no `$ref`, `const`, `oneOf`, `allOf` or type arrays;
a plain object root; `anyOf` only on its own). Calls are still validated against
the full schema server-side. Everything a tool returns validates against its
advertised `outputSchema`; an output whose root cannot be a plain object (the
`plur_*` proxies, whose backend may return any JSON value) is listed without an
`outputSchema`. An advertised input schema can be wider than what the server
accepts, because a constraint the lowering has to drop is repeated in that
parameter's description and still enforced; it is narrower in one case only: an
explicit `null` for a nullable optional parameter is accepted by the server but not
advertised.

Some rules relate parameters: `patch_note` needs `content` for `append`, `prepend` and `replace`,
accepts optional `insert_before` only for `append`, and needs `old_string` with `new_string` for
`replace_text`. A portable schema cannot express that (it has no `if`/`then`, and
`oneOf`/`allOf` at the root break several clients), so the server does not advertise it as schema
keywords. The rule is written into the tool's description and into each parameter's description
instead, and a call that breaks it is refused with a message naming the operation and the field.

For how to connect and call these over MCP — stdio or HTTP, auth, and the discover → describe → call flow — see the [API Reference](https://docs.the40thieves.dev/reliquary-tc/tools/api-reference.md).

## Tool-surface facade

What `tools/list` advertises is controlled by `toolFacade.mode`:

* **`triad`** (default) — three meta-tools: `find_capability` (BM25 search over the
  catalog), `describe_capability` (a tool's schema + scopes), and `call_capability`
  (invoke by name). Discover, inspect, then call. Two standard knowledge-connector tools
  ride alongside them: `search` and `fetch` (see below), so ChatGPT deep research and
  company knowledge, which only recognise tools by those names, find them without a
  discovery round trip. They are the only tools promoted, unless `toolFacade.triadHotPath` is on:
  then `read_note`, `search_vault`, `write_note` and `list_notes` are listed beside them too. Hide
  them with `toolVisibility.hidden: [search, fetch]`.
* **`domain`** — \~a dozen domain meta-tools (`notes`, `search`, `vault`, …), each
  taking `{ action, args }`.
* **`flat`** — the full underlying surface.
* **`auto`** — **deprecated; set an explicit mode.** It resolves to `triad` for
  every client, so it is the same as setting `triad` and adds nothing. The
  setting is still accepted, so no existing config breaks, but `reliquary-tc
  doctor` and `server_health` report it as deprecated, and it will be removed in
  the next major version. An operator's own `toolFacade.autoClients` entry (a
  case-insensitive substring of the client's `clientInfo.name` mapped to a mode,
  checked in the config's own key order) still takes effect under `auto` and is
  deprecated with it.

  **Why.** The built-in per-client table used to send `claude-code` to `domain`.
  The measurement that followed does not support that pick: with Claude Code's
  own tool search on, `domain` matched `triad` on success and added argument
  validation errors in every trial (the model cannot see a domain action's schema
  before calling it), and `flat` cost about 38% more billable tokens. No mode beat
  `triad` by the pre-registered margin. The project also decided against
  client-sniffing: MCP 2026-07-28 says list endpoints no longer vary per
  connection. Set one explicit `toolFacade.mode` per client; see
  [Choosing a facade mode per client](https://docs.the40thieves.dev/reliquary-tc/getting-started/mcp-clients.md#choosing-a-facade-mode-per-client)
  for the measured recommendations (`triad` for Claude Code, `domain` for Codex).

  **Explaining an `auto` decision.** `toolFacade.explainAutoMode: true` (default
  `false`) writes one `reliquary-tc toolFacade.explain {...}` JSON line to stderr
  per resolution, and the `explanation` field of `server_health`'s `toolFacade` block returns the
  same record for the calling client: the observed `clientName` (bounded, control
  characters stripped), the `configuredKeys` and `builtInKeys` checked, the
  `rule` that fired (`no-client-name`, `configured-override`, `built-in-table` or
  `no-match`), the `matchedKey`, the `fallback` and the `mode` chosen.
  The same block carries a `deprecation` notice whenever the configured mode is
  `auto`. `reliquary-tc doctor` warns that `auto` is deprecated
  and, separately, warns when `autoClients` or `explainAutoMode` is set under a
  mode other than `auto`.

Every underlying tool stays callable by name in every mode, and `tools/list` is
filtered per caller scopes + tool-visibility ACL. Routing always goes through the
same authorization / ACL / HITL / idempotency / throttle pipeline.

## Tool profile

`toolFacade.mode` (above) picks what a given **session** is advertised. A separate,
deployment-level setting, `toolFacade.profile`, picks which tools are **visible and
callable** at all. Registration itself never changes — every tool is always
registered (`server_health`/`inspect_visibility` can always name all 164) — only
dispatch-time visibility does:

* **`full`** (the default) — every tool stays visible/callable, exactly as today.
  **This ticket does not change the default.** A usage report over 4,787 recorded
  calls (GitHub issue #877) found 97 of 164 tools never called once — but it names
  only five tools as confirmed zero-call, not whole families, and the same
  reporter separately filed a whole issue (#879) praising one of the tools an
  earlier draft of this feature would have hidden. Flipping the default needs its
  own evidence-gated decision, not a side effect of adding the mechanism — see
  `docs/adr/` for that bar.
* **`core`** (opt-in) — a smaller, curated surface for an operator who wants one.
  Five graph-analysis tools (`graph_centrality`, `graph_communities`,
  `suggest_links`, `find_link_cycles`, `prune_hub_links`) are the ONLY ones with
  direct usage evidence behind the cut (#877 names them explicitly as zero-call).
  The rest of the curation — the structured-document family (Bases, Canvas,
  Kanban, periodic notes, bookmarks, attachments, tables) and the plugin-bridge
  family (Excalidraw, MakeMD, Remotely Save, OCR, git, Templater, QuickAdd,
  Dataview, and siblings) — is a STRUCTURAL choice (every member proxies to a live
  companion plugin and degrades when it is absent), not a usage claim; #877 gives
  no evidence either way for these. `bundle_files`/`bundle_folder` stay in `core`
  despite living in the plugin-bridge domain: both are pure filesystem (no
  companion dependency) and `bundle_folder` has direct positive usage evidence
  (#879). Everything the triad facade, the memory tools (M5/M7/M8), catalog
  discovery, health/admin, or the HITL/elicit flow depends on stays in `core`
  regardless of usage. See `packages/server/src/mcp/tool-profiles.ts`'s module
  comment for the full accounting, including the caution that a documented history
  of plugin-bridge integration bugs (companion routes 404ing, a wrong plugin-id
  mapping) means zero calls to that family cannot be read as zero want.

A tool `core` hides is not silently missing: `find_capability` discloses a
profile-hidden match by name and count when your query matches one;
`describe_capability`/`call_capability` on one by name both answer a
`capability_hidden` error naming the config key, never a bare "not found" and
never a silent dispatch; `inspect_visibility` reports `disabled_by_profile`.
`toolFacade.profile` is the default (`"full"`) unless you set it — no migration
needed.

## Tool-budget profiles

Some clients cap how many tools they accept: Antigravity and Windsurf 100, Gemini
Enterprise 100 actions, VS Code, Copilot Studio and Vertex 128 per request, and Codex
defers everything past 100. A client can pick an **advertised subset** per URL on the
HTTP transport, or you can set one for the whole server with `toolFacade.advertise`
(default `"all"`, which narrows nothing). A subset is advertised flat, whatever
`toolFacade.mode` says, and it is advertisement only: a tool outside it stays
registered, authorized as always, and callable by name. This is different from
`toolFacade.profile`, which decides what is callable at all.

| URL | Advertises | Notes |
| :- | :- | :- |
| `/mcp` | what `toolFacade.mode` / `advertise` say (the triad by default) | unchanged |
| `/mcp/triad`, `/mcp/domain` | the triad, or the domain meta-tools | for a server whose default is something else |
| `/mcp/essentials` | about 35 curated tools, flat | one or two per domain, none needing a companion plugin; fits 100-tool caps. `search` and `fetch` join it when the server registers them |
| `/mcp/core` | the `core` curation above, flat (101 tools) | fits 128-tool caps, not 100 |
| `/mcp/full` | every registered tool, flat | for clients with no cap, or that defer-load |

An unknown name under `/mcp/` answers 404. The URL wins over `toolFacade.advertise`.
Stdio has no URL, so it selects a subset by config only. OAuth-protected deployments keep
one resource (`auth.resource`, the `/mcp` URL): every `/mcp/<name>` URL is also a name for it. A
client given `/mcp/essentials` is challenged with, and signs in against, metadata whose `resource` is
that URL, and a token for any of these URLs works on every surface, as profiles change what is
advertised and never what is authorized. See
[Profile URLs and OAuth](https://docs.the40thieves.dev/reliquary-tc/security/auth-model.md#profile-urls-and-oauth).

The server `instructions` open with one routing sentence for the surface the client was
given, complete inside the first 512 characters (Codex truncates there) and well inside
Claude Code's 2,048. The triad's three tools, and the `search` and `fetch` advertised beside them, carry `_meta` `"anthropic/alwaysLoad": true`
so Claude Code loads them upfront instead of behind its tool search. With `toolFacade.triadHotPath` on,
the four hot-path tools carry it too.

## Tool tags

Every tool carries a set of tags, and `toolVisibility.hiddenTags` / `disabledTags` act on them.
Naming a tag in `hiddenTags` drops its tools from `tools/list`, `find_capability`, the
`reliquary-tc://catalog` resource and the domain meta-tools while leaving them callable by name;
naming it in `disabledTags` also rejects the call, as if the tool were never registered. Each
tool's page in the [Tool Catalog](https://docs.the40thieves.dev/reliquary-tc/tools/tool-catalog.md) lists its tags, and `describe_capability`
returns them as `tags`.

Most tags are **derived** at registration from what the tool already declares, so they cannot
drift: a tool's scopes say whether it writes, its destructive and confirmation flags say whether
it can destroy data, and its facade domain gives its `domain:` tag. A few facts no other field
carries are **declared** on the tool definition. Registration refuses a tag outside this
vocabulary, a derived tag written by hand, and a declaration the derivation already makes.

| Tag | Source | Meaning |
| - | - | - |
| `read-only` | derived | Does not mutate the vault: no write, delete, bulk or execute scope, and not destructive. The same test as the read-only gate and the MCP `readOnlyHint`. |
| `writes` | derived | Mutates the vault. The complement of `read-only`. |
| `destructive` | derived | Can destroy data, always or on some calls (the MCP `destructiveHint`). |
| `hitl` | derived | Needs a human confirmation token, always or when a call crosses a boundary. |
| `bulk` | derived | Holds a `bulk:*` scope: one call changes many notes. |
| `admin` | derived | Holds an `admin:*` scope: administers the server, its vaults, ACLs, config or metrics. It may change server state without modifying notes, so it can also be `read-only`. |
| `domain:<name>` | derived | Belongs to that facade domain, for example `domain:git` or `domain:notes`. |
| `plugin-bridge` | derived and declared | Needs the Obsidian companion plugin, so a live Obsidian session. Derived from a scope that names a plugin; declared for the few bridge tools whose scope is a generic vault scope. |
| `external-network` | declared | The tool's handler may send query or note text to a service outside the server process: a hosted embedding provider, an LLM judge (the gateway or TypeSafe), or a cloud sync plugin. Indexing that runs in the background after a write is not attributed to the tool that triggered it. |
| `client-sampling` | declared | The tool asks the calling client's own model to run a completion (MCP sampling) and sends it note text the caller may already read. The client decides whether to prompt its user and whose tokens pay for it. The tool has a non-sampling fallback, so `disabledTags: ["client-sampling"]` removes it only for deployments that want no sampling request at all. |
| `experiential` | declared | Reads or writes the derived work-memory plane. |
| `verdict` | declared | A verdict verb: its calls are recorded as verdicts, never as evidence for later retrieval. |
| `knowledge` | declared | Part of the knowledge-retrieval surface. |
| `search` | declared | Retrieves notes or chunks by query. |
| `docs` | declared | Reads the external vendor-docs corpus. |
| `links` | declared | Reads the link graph. |
| `graph` | declared | Computes graph analytics over the link graph. |
| `provenance` | declared | Reports where an answer came from. |
| `diagnostics` | declared | Explains or audits retrieval behaviour. |

For example, `hiddenTags: ["destructive"]` keeps every tool that can delete or overwrite out of a
client's discovery, and `disabledTags: ["external-network"]` makes a deployment that must not call
a hosted embedding provider refuse those tools outright.

## Domains

| Group | Domains | Examples |
| - | - | - |
| **Notes & metadata** (6 tools `full`-only) | notes, frontmatter, properties, tags, links, headings | `read_note`, `write_note`, `patch_note`, `update_frontmatter`, `get_backlinks`; graph analysis is `full`-only: `graph_centrality`, `graph_communities`, `suggest_links`, `find_link_cycles`, `prune_hub_links`; `suggest_tags` (client-sampled tag suggestions) is `full`-only too |
| **Search & retrieval** | text search, DQL, vector / hybrid search, embeddings | `search_vault`, `search_dql`, `search_semantic` |
| **Structured formats** (`full`-only) | Bases, Canvas, periodic notes, bookmarks, outlines | `read_base`, `update_canvas`, `create_periodic_note`, `list_bookmarks` |
| **Plugin bridges** (`full`-only) | Dataview, Templater, OCR, command execution, tasks, workspace | `eval_dataview_field`, `execute_template`, `execute_command`, `list_tasks` |
| **Memory & capture** | memory store, capture queue, workspace traces, PLUR proxy | `add_observation`, `enqueue_capture`, `plur_recall` |
| **Knowledge & context** | GraphRAG, composite context, reflection, red-team challenge | `vault_graph_search`, `vault_context`, `reflect`, `knowledge_challenge` |
| **Work memory (experiential)** | quarantined agent-episode store with an eligibility-gated reader contract | `work_search`, `work_episodes`, `work_forget`, `record_retrieval_feedback` |
| **Git & sync bridges** (`full`-only) | Obsidian Git (commit is HITL-floored), Remotely Save backup signal | `git_status`, `git_diff`, `git_commit`, `remotely_save_status` |
| **Bulk & URI** | bulk note create / move / set-property, `obsidian://` URI generation, plus `bundle_files`/`bundle_folder` (filesystem-only, kept in `core`) | `bulk_create_notes`, `bulk_move_notes`, `bulk_set_property`, `generate_uri`, `bundle_folder` |
| **Server admin** | health, config, ACL, metrics introspection | `server_health`, `get_server_config`, `inspect_acl`, `get_metrics` |

See the [Tool Catalog](https://docs.the40thieves.dev/reliquary-tc/tools/tool-catalog.md) for the per-tool Profile column (generated from
`tool-profiles.ts`, the single source of truth this table's `full`-only markers also read from).

## Property links (Obsidian parity)

The link tools (`get_outgoing_links`, `get_backlinks`, `find_unresolved_links`, `find_orphans`,
`vault_health_score`, `rewrite_link` and the backlink update in `move_note`) see the wikilinks a note
keeps in its **properties**, the way Obsidian does (`CachedMetadata.frontmatterLinks`, Obsidian 1.4.0
and later), not only the ones in its body. The graph index records them too.

```yaml theme={null}
---
author: "[[Douglas Adams]]"
related:
  - "[[The Hitchhiker's Guide]]"
  - "[[Dirk Gently|Dirk]]"
---
```

* **Quote the link.** Obsidian's own rule ("internal links must be surrounded by quotes"): a quoted
  `"[[X]]"` is a YAML string and counts; an unquoted `author: [[X]]` is a nested YAML list, not a
  link, in Obsidian and here.
* **Which values count.** A wikilink inside any string value: a text property, any item of a list
  property, or a string nested in a mapping. The syntax is the body's: `[[X|alias]]`, `[[X#Heading]]`
  and `[[X#^block]]` resolve the same way. Numbers, booleans and dates hold no links.
* **How they appear.** A property link carries `source: "property"` and `property`, the top-level
  property it sits under (a nested value reports its top-level key). A body link has neither field, so
  a vault with no property links returns exactly what it always did, in both response formats. A
  property link's `line`/`col` are positions in the note file; a body link's `line` counts from the
  first body line.
* **Same rules as body links.** An unresolved property link is an unresolved link; a link to a note the
  caller cannot read is unresolved exactly like a missing one; a note linked only from a property is not
  an orphan; `move_note` and `rewrite_link` repoint property links and keep their quotes, alias and
  heading.
* **Malformed YAML.** A note whose frontmatter does not parse has no property links (nothing can be
  read from it), is named in the result's `warnings`, and its body links still count.
* **Graph search.** Property links are indexed as `property_link` edges, separate from body
  `links_to` edges. `vault_graph_search` follows them only when `retrieval.densify.includeInWalk` is on
  (the existing gate for edges beyond body wikilinks), so default ranking does not change when a vault
  starts using property links. The graph analysis tools see them regardless. Notes in Obsidian's
  Excluded files stay link targets (a property link to one resolves) and, as for body links, get no graph
  edge.

## Renaming and link-safe names

`move_note`, `bulk_move_notes` and `move_attachment` rewrite the links in every note that pointed at
the old name (`update_backlinks`, `update_references`), and `rewrite_link` rewrites them to a target
you supply. The new name is written into `[[...]]`, `![[...]]` and `[text](...)` in those notes, so
two guards keep a name from becoming link syntax:

* **A new name must be able to live inside a wikilink.** A note or attachment you would CREATE, move,
  rename or copy to (`write_note`, `copy_note`, `move_note`, `bulk_move_notes`, `write_attachment`,
  `move_attachment`, `create_canvas`) may not have a path segment containing `[`, `]`, `#`, `^`, `|`,
  `%%`, a newline or any other control character. The call is refused with `invalid_input`, the
  message names the offending characters (never the name), and nothing is written. This follows
  Obsidian's own link rule, which says a name with `# | ^ : %% [[ ]]` "may not work as a link" (`:` is
  already refused as a Windows-hostile name, `path_invalid`). Only a NEW name is judged: a file or folder
  that already has such a name keeps working, can be read and updated in place, and can be moved or
  renamed away to a safe name.
* **Every rewritten link is proven.** After a rewrite changes a link, the new text is parsed again and
  must be exactly one link, pointing at the intended target, with its heading and alias unchanged and
  nothing around it. Otherwise the call is refused with `invalid_input` and none of the notes are
  changed. This is what protects `rewrite_link`, whose `to_target` is free text: a target such as
  `x]]` followed by a newline and text, or one containing `|`, is refused. A target may still end in
  its own `#Heading`. In a note's properties the new target additionally must not contain `[[`, `]]`,
  `|`, `%%` or a line break.
* **The whole rewrite is planned and proven before anything moves, and committed as one batch.**
  `move_note`, `bulk_move_notes` and `move_attachment` compute every note's new text, prove every
  changed link and scan every body with memoryDefense before they touch a file. If one link cannot be
  written, the call is refused with `invalid_input` naming the note it sits in and the target it would
  have carried, nothing is moved or written (for `bulk_move_notes`, the whole batch is refused), and a
  retry is an ordinary refusal, not an `indeterminate_outcome`. A note you cannot read is never named:
  the refusal says only that such notes exist (`details.hidden_notes: true`, a flag and never a count). A note that cannot be read at all, such as a hard-linked file, is refused the same way, except in `bulk_move_notes` when it is not one of the moves: it is skipped, and the result carries `unreadable_skipped` (a count, never a path) and `unreadable_warning` to say its links were not updated. Notes in a wiki's immutable raw
  folder are skipped and reported before any of this, so an unrepresentable link in one never refuses
  the move. Two things reach the refusal even though the destination's NEW segments pass the name
  check above. A path-qualified link into an EXISTING folder whose name holds `#` or `^` (`C#/Note`)
  would be read as a heading or block reference, so a path-form link must come back from the re-parse
  exactly as written; when the new basename is unique, the bare link `[[Note]]` is written instead and
  the move goes ahead. And a markdown link cannot carry a `)` in its target, since the scanner ends the
  link there and has no `<...>` form: moving a note to `Report (final).md` is refused while a
  `[text](...)` link points at it, and fine while only `[[wikilinks]]` do.
* **The move and its rewrites commit together or not at all.** The moved note and every backlink
  rewrite are written as one batch: each linking note is replaced only if it still holds the bytes the
  plan was made from, and a write error or a concurrent edit rolls the whole batch back, the move
  included. If a linking note changed, or a new one appeared, between the plan and the commit, the plan
  is rebuilt and re-proven once; a second change is refused as `concurrent_modification` with nothing
  moved. Each rewritten note is snapshotted first, so `restore_note` can undo the rewrite. The source
  is deleted last; the steps after the batch (deleting the source, the search-index updates) are the
  only ones with no rollback.

## Wiki checks (page-exists and lint)

Two read-only tools keep a wiki from growing duplicates. Both are advisory: they never write a note
and never block a write, so an agent that ignores them loses nothing. Both are `full`-profile tools
(hidden under `toolFacade.profile: "core"`).

**`find_existing_page`: before `write_note`.** Give it the topic you are about to write about. It
returns a `verdict` and the candidate notes with the evidence for each:

| Verdict | Meaning | Suggested action |
| - | - | - |
| `exists` | Identity evidence names exactly one page: its path or file name, an `aliases` entry, a `wikidata:` property holding the same QID, or its title or H1. | Link to or extend that page. |
| `ambiguous` | Several pages match on identity, or only soft evidence exists: other notes already link the text, or a note is semantically near. | Read the candidates, then decide. |
| `new` | Nothing matched. | Create the page. |

Semantic similarity alone never produces `exists`; the calibration below is why. The [LLM judge](#the-llm-judge) can resolve an `ambiguous` verdict.

**`lint_wiki`: periodic upkeep.** One call runs the existing health checks and a note-level
near-duplicate pass, and returns **proposals**: each is `\{ kind, subject, related?, detail,
suggested_action, tool, tool_args?, evidence? \}`, where `tool` is the tool that applies the fix. Kinds:
`orphan`, `unresolved_link` (grouped per missing target), `contradiction` (open rows only), `stale`,
`duplicate_chunks`, `missing_sources`, `coverage_gap` (from the latest persisted gap report) and
`near_duplicate`. A check that cannot run (no rollup yet, no embeddings) is listed under `skipped`
instead of failing the call. `response_format: "concise"` drops `detail`, `tool_args` and `evidence`.

**Access rules.** Both tools honour the read ACL (a note the caller cannot read behaves exactly like a
missing one) and Obsidian's Excluded files: an excluded note still counts as a link target and as
identity evidence (its name or alias is a real name to avoid), but never appears as a similarity match
and is never the subject of a `lint_wiki` proposal.

**Scheduled lint (opt-in).** `maintenance.wikiLint.enabled: true` runs the same checks every
`intervalHours` (default 24) over the whole vault, or `folder`, capped at `maxNotes` (default 1500)
for the pairwise pass. It only logs one summary line per vault (proposal counts by kind) and persists
nothing, so it cannot change a note. It is off by default and also needs `maintenance.enabled`.

**Calibration (bge-m3, public evergreen corpus).** The similarity floors were chosen by a
pre-registered study (hash `73c690843c882c0a754da2841d1e88a88886d05e5c02e45a8eb387367d72fa31`):
60 sampled notes, each with an LLM-written topic, rewrite and summary, scored against its 2 nearest
and 2 random other notes, with the first 30 notes for choosing thresholds and the last 30 held out.

| Score | AUC (choose / held-out) | Floor (max recall at precision >= 0.90, chosen split) | Held-out |
| - | - | - | - |
| Topic to note, best chunk (R2) | 0.774 / 0.833 | 0.708 | 0 pairs predicted |
| Topic to note, mean-pooled note vector (R1) | 0.760 / 0.807 | 0.708 | 0 pairs predicted |
| Note to note (`lint_wiki`) | 0.903 / 0.889 | 0.909 | precision 0.00 (2 false pairs), recall 0.00 |

Best-chunk scoring is used because it was within 0.01 AUC of the mean-pooled vector and needs only a
chunk nearest-neighbour search. The honest reading is that the precision >= 0.90 constraint is only met
at the very top of the score range, where recall is a few percent: in a corpus where every note is on one
subject, near-neighbours and true duplicates overlap. So similarity is **candidate evidence only**
(`ambiguous`, or a `near_duplicate` proposal to review), never a verdict, and a held-out precision below
0.85 is reported as a failure of the band, not tuned away. Over the whole corpus, the best-chunk top 10
holds the source note for 33 of 60 topics, so lower `min_similarity` per call (for example 0.6) to see weaker
candidates. The floors are specific to `BAAI/bge-m3`; on another embedding model treat them as a starting
point.

### The LLM judge

Because similarity cannot decide "same topic", a model can read the candidates. The judge runs through
the gateway `judge` role by default, or through TypeSafe Jev with `wikiJudge.provider: typesafe`
(see [`wikiJudge`](https://docs.the40thieves.dev/reliquary-tc/configuration/config-yaml/)); with neither configured, there is no judge and nothing
changes. For `find_existing_page` it is **off by default** (`wikiJudge.enabled: false`; `judge: true` on a
call turns it on for that call). For `lint_wiki` and the scheduled lint it is **on by default whenever a
judge is configured** (`wikiJudge.lintEnabled: true`, `maintenance.wikiLint.judge: true`); `judge: false`
on a call, or `lintEnabled: false`, turns it off. The scheduled lint itself still needs
`maintenance.wikiLint.enabled: true`.

* **`find_existing_page` `judge`.** Only a verdict of `ambiguous` that rests on soft evidence (similarity,
  link text) is judged; an exact name, alias, `wikidata:` or title match is final and never sent. Up to
  `wikiJudge.maxCallsPerRequest` (1 to 3, default 3) top candidates are judged, each answered
  `same_topic`, `overlapping` or `different` with a one-sentence reason. Exactly one `same_topic` makes the
  verdict `exists` (with `judged_by: { model, verdict, rationale, paths }`); every candidate judged
  `different` makes it `new`; anything else, and any failure, stays `ambiguous`. The prompt tells the
  judge to prefer `overlapping` when unsure.
* **`lint_wiki` `judge`.** Each `near_duplicate` proposal can carry a `judge_verdict` (up to
  `max_judge_calls` per call). `maintenance.wikiLint.judge: true` makes the scheduled pass judge too, capped
  at `maintenance.wikiLint.judgeMaxCalls` per run, and logs the verdict counts. Both default on once a
  judge is configured, because the judge only adds a verdict to a proposal and the daily cap bounds the
  spend. `lint_wiki` now carries the `external-network` tag, so `toolVisibility.disabledTags: ["external-network"]` removes it (set `wikiJudge.lintEnabled: false` to keep the tool without the judge),
  and the scheduled pass skips its judge under that tag instead of calling out.
* **TypeSafe Jev (`wikiJudge.provider: typesafe`, experimental).** Jev is asked a Choice question over
  `same_topic`, `overlapping` and `different` and returns probabilities; a pair is `same_topic` when its
  probability reaches `wikiJudge.threshold`, otherwise the likelier of the other two. `model` must be a
  pinned, dotted version (`jev-1.13.0`, never a floating alias) and `threshold` has no default: it is a
  ranking score, not a calibrated probability and not a security control, so tune it on labelled pairs from
  your own vault. It never falls back to the gateway, and a missing key or bad block disables the judge
  with a warning rather than changing provider. The base URL must be `https://` unless it is loopback or
  its exact hostname is listed in `wikiJudge.plainHttpHosts` (a gateway pass-through on a private network;
  see [Plain-http endpoints](https://docs.the40thieves.dev/reliquary-tc/configuration/config-yaml.md#plain-http-endpoints-plainhttphosts)). The same
  egress rules apply as for the gateway judge.
* **Caps.** `wikiJudge.maxCallsPerDay` (default 200, `0` disables) bounds gateway calls per UTC day across
  every caller; a failed call counts, and the call is reserved before it is sent. `wikiJudge.timeoutMs`
  (default 15000) is a per-call deadline that also cancels the gateway request. `wikiJudge.maxNoteChars`
  (default 2400) cuts each side of a comparison, so one call has a bounded size. Over a cap, or on any
  error, the verdict stays `ambiguous` and the tool still answers.
* **Cache.** One verdict per (subject, candidate, resolved model) in `cache.db`, keyed on content hashes:
  editing a note or a gateway repoint of the `judge` alias (the resolved `provider/model` is recorded, never
  the alias) re-asks; a repeat costs nothing. No page text is stored.
* **Privacy.** The topic and the opening text of the candidate pages (at most `maxNoteChars` each) go to the
  judge (the gateway model, or TypeSafe with `provider: typesafe`). A note is sent only if the caller may read it (ACL), it is outside `egress.excludePaths`
  and outside Obsidian's Excluded files; such notes are never sent and are listed as `unjudged`. `maxCallsPerDay: 0`
  or no judge configured keeps everything local. `reliquary-tc doctor` (check `wiki.judge`) reports the provider, the model, today's&#x20;
  calls and failures.
* **Model note.** The gateway's `judge` alias served `openai/gpt-6-sol` when this was measured. That model
  answers HTTP 400 to `temperature` and `max_tokens`, so the judge request sends neither.

**Judge study (public evergreen corpus, same 60 notes and 30/30 split as the calibration).** Pre-registered
before any judge call (hash `97eae3b09719f489ac4e7fe8733580cfa279eb10e07515f2dc2d0ccefa704e45`, judge prompt
and code frozen). Gold labels are not from the judge's family (OpenAI): positives are Gemini-written
rewrites, summaries and topics; negatives were labelled by a Claude model. 1200 judged items, `openai/gpt-6-sol`,
about 2 s per call. Arms: **A** embedding-only at the shipped floor; **B** judge over candidates at the
floor; **C** judge over the top-3 nearest whatever their cosine.

| S1 topic to page (held-out, 31 positives) | precision | recall | F1 |
| - | - | - | - |
| A, floor 0.708 | no pair flagged | 0.00 | 0.00 |
| B, judge at the floor | no candidate to judge | 0.00 | 0.00 |
| C, judge over top-3 | 1.00 (6/6) | 0.19 (6/31) | 0.32 |

C was perfectly precise (no false `same_topic` in 331 gold-negative items, including topics whose page was
removed), but it found only 12 of 63 pages: the top-3 holds a gold page for 28 of 63 topics, and of the 29
gold candidates the judge saw it answered `overlapping` for 17 on a three-to-eight-word topic. The pre-registered rule for turning
the judge on by default needed a recall lift of 0.25 over embedding-only on the held-out split, and C's was
0.19, so **`wikiJudge.enabled` ships `false`**. B has almost nothing to judge, because the floor passes 5 of 360
candidates. A follow-up could judge the top-3 whatever the floor says, but the study does not support
it yet. For note pairs (`lint_wiki`), the judge over the 840 labelled pairs had precision 0.92 and recall
0.95 (held-out 0.90 / 0.95); 8 of its 10 disagreements with the title-only labels were real duplicates on a
full read by a second model, so the lint judge is on by default once a judge is configured (it only adds a verdict to a proposal), while the `find_existing_page` judge stays off. With 31 held-out positives the
intervals are wide; this is one corpus, one embedding model and one judge model.

**TypeSafe Jev against the gateway judge (note pairs, same corpus and split).** A second pre-registered study
(written and hashed before the first Jev call; one earlier connectivity call and the known `openai/gpt-6-sol`
held-out result are disclosed in it) asked whether Jev (`jev-1.13.0`) is non-inferior to the gateway judge's
recorded verdicts on the 840 labelled `lint_wiki` pairs. Jev's `same_topic` probability threshold was tuned on the
30-note calibration split only, and the 30-note held-out split was scored once. Non-inferiority needed, for
precision and for recall each, a point difference no worse than 0.05 absolute and a one-sided 95% paired-bootstrap
lower bound no worse than -0.10 (10,000 resamples, seed 1328). **Result: Jev was non-inferior at that margin on
both metrics, so Jev is the recommended lint-judge provider on Cave** (`wikiJudge.provider: typesafe`); the gateway
judge remains the default provider. With about 63 held-out positives the power is low, and it is one corpus, one
embedding model and one threshold. TypeSafe's customer agreement bars publishing benchmark figures, so no Jev
precision, recall, latency or threshold is published here: the figures and the tuned threshold stay with the operator
(tune the threshold on labelled pairs from your own vault). The `find_existing_page` judge is unchanged: the
topic-to-page recall that kept it off was measured with the gateway judge and has not been re-measured for Jev.

## Wiki workflow (draft and commit a page)

Two more `full`-profile tools take a wiki page from topic to a linked, schema-checked note. They split
the work so the server does the bookkeeping and **the LLM writes the prose**: neither tool generates
page text.

1. **`find_existing_page`** (above): is there already a page on the topic?
2. **`draft_wiki_page`** (read-only): runs the same duplicate check, then returns the existing page if
   there is one, a **link map** (`link_to`: notes the page should link, `link_from`: notes that should
   link to it, `already_linking`), the SCHEMA.md requirements for the page `type`, and a changeset
   skeleton (a proposed path, frontmatter and a patch per note to link from). It writes nothing.
3. **You write the page body**, using the notes the link map names.
4. **`commit_wiki_page`**: applies the changeset in one step, the new page plus additive patches
   (`link`: a bullet under a heading such as `See also`, added once; `append`: text at the end or under a
   heading) that link the rest of the wiki to it.
5. **`lint_wiki`** (above) is the periodic upkeep: orphans, unresolved links, stale or duplicate pages.

**SCHEMA.md.** Set `vaults[].wiki.folder` (for example `wiki`) and put a `SCHEMA.md` in it. Its
frontmatter declares the page types, the frontmatter each requires, the subfolder new pages of a type go
in, and the allowed property vocabulary (a list of names, or a map of name to allowed values; an empty
value means any). The body is free prose and is never parsed.

```yaml theme={null}
---
types:
  concept:
    description: An idea or term
    required: [type, summary, sources]
    folder: concepts
  person:
    required: [type, summary]
properties:
  type: [concept, person]
  summary:
  sources:
  status: [draft, stable]
---
```

Obsidian's own `tags`, `aliases` and `cssclasses` are always allowed. SCHEMA.md is read as a bounded
file: one over 64 KiB is not parsed, and a section over 100 types, 100 fields per type, 500 properties,
200 values per property or 200 characters per name or value is cut, each with a warning. A SCHEMA.md
that cannot be read is a `schema_file` problem, never an error. A `conventions:` block can mark a rule `severity: block`, which refuses a write that adds its violation; see [Vault conventions](https://docs.the40thieves.dev/reliquary-tc/guides/vault-conventions.md).

**The wiki folder is required.** `commit_wiki_page` refuses (`invalid_input`, `reason: no_wiki_folder`)
in a vault with no `wiki.folder`, and refuses a page outside it (`reason: outside_wiki_folder`). The
page path is judged as written (`..` and absolute paths are `path_invalid`) and again after symlinks,
and "inside" means the same directory as the filesystem sees it (the folder's device and inode against
each directory above the page), never a string comparison: `Café` in two Unicode forms and `Wiki` against
`wiki` are one directory on some volumes and two on others, and no spelling can make two different
directories equal. So neither a sibling folder that shares the prefix, a case or Unicode variant nor a
symlink out of the folder can carry a page past the check. While the folder does not exist yet only its
exact configured spelling is accepted. The folder itself must be a plain relative path in the config:
`.`, `/`, an empty string, an absolute path and `..` are rejected, never reinterpreted. A segment
ending in a space or dot is rejected too, because Windows strips those suffixes. The same rule applies
to `wiki.rawFolder`.

**Scopes.** The tool needs `read:notes` as well as `write:notes`: the duplicate check reads every note
the caller may read and names the matches.

### Ingesting a raw source

The wiki is built from sources you collect and do not edit: web clippings, papers, transcripts. Each vault
has a **raw folder**, `vaults[].wiki.rawFolder`. It defaults to `raw` **beside** the wiki folder (`wiki`
gives `raw`, `notes/wiki` gives `notes/raw`) and is not set at all when that would be the wiki folder
itself; it must never be, contain or sit inside the wiki folder (the config refuses it), so a raw note
can never be a wiki page or a `lint_wiki` subject. It is validated like `wiki.folder`.

**The raw folder is immutable.** It is the folder ACL's own rule, built per vault from the config: no
tool writes, creates, renames or deletes anything in it (`acl_denied`), for any caller and whatever the
vault's `writePaths` / `deletePaths` say. Reads follow the normal read ACL. A path counts as raw by its
name and by where it really leads, so a symlink in the wiki that points into `raw/`, or one inside
`raw/` that points out, does not make a source writable. `commit_wiki_page` therefore refuses a page,
an overwrite or a patch that targets it, and refuses the whole commit. Add sources outside the server
(Obsidian, a web clipper, the file system). Raw notes are inputs, so they are never `find_existing_page`
or `draft_wiki_page` candidates and never offered as a `link_from` patch.

**Renames leave raw notes alone.** `move_note`, `bulk_move_notes` and `move_attachment` repoint the
links in every note that links the moved target, but never in a raw note. The move proceeds; each raw
note that links the target is left as it was, so its link now points at the old name. The result says
so: `immutable_not_updated` lists those notes you may read, `immutable_not_updated_hidden` counts the
ones you may not (a count, never a path), and `immutable_warning` explains. Repoint them outside the
server. If `raw` is a symlink to another folder in the vault, that folder is immutable too (from the
next server restart), is raw under its real name everywhere (duplicate checks, `lint_wiki`, the judge:
with `raw -> sources`, `sources/Topic.md` is a source, never an existing page), and the raw folder and
wiki folder must not be the same directory.

**Ingest.** Pass one raw note to `draft_wiki_page` as `source` (a `.md` note inside the raw folder, with
the `topic` of the page it feeds). You get the usual duplicate check, link map and changeset skeleton,
and the server does the bookkeeping:

* the note is cited in the skeleton's `sources` as a property link (`[[raw/Clip]]`) and appears in the
  link map as a `source`;
* `ingest` reports it: `path`, `content_hash`, `chars` (the body, frontmatter excluded), `title`, and
  `cited_by`, the wiki pages that already link it (so you can see it was ingested before);
* you read it with `read_note` and write the prose; the server never calls a model here, apart from the
  optional dedupe judge `find_existing_page` already has, which never sees a raw note.

**A page must compress something.** A source under **1500 characters** is refused a page of its own when
nothing in the wiki can take it in: no page covers the topic, none is related to it and none already
cites it. The answer then has no changeset and `ingest.refused` is `\{ reason: "source_too_short", chars,
min_chars \}`: wait for more sources on the topic, or add it to a page that exists. With a page that
covers, relates to or cites it, a short source is fine. The rule is advisory advice from the draft step;
the security rules (immutable raw, no raw page) are enforced by `commit_wiki_page` and the ACL.

**A source you may not read never leaks.** A `source` the read ACL denies answers exactly like one that
does not exist (`note_not_found`), before any byte of it is read; a path outside the raw folder is
`invalid_input` (`reason: outside_raw_folder`), judged on the filesystem like the wiki folder (the
folder's device and inode against each directory above the path, as written and after symlinks); a vault
without a raw folder is `invalid_input` (`reason: no_raw_folder`); a raw folder that leaves the vault
or whose identity cannot be established is `invalid_input` (`reason: raw_folder_unsafe`); a non-markdown
file is refused (`reason: not_markdown`). The read check comes first, so a read-denied symlink answers
`note_not_found` like a missing file.

**Problems versus errors.** Things for you to fix do not block the write; they come back in
`problems`: `schema` (missing required field, unknown type or property, value outside the vocabulary),
`unresolved_link`, `missing_link` (a related note the page does not link), `no_inbound_link`,
`patch_without_link`, `patch_skipped` (the note already links the page), `possible_duplicate`,
`excluded_note`, `poison_suspect`, `redacted`. Generated-page work runs after the response and reports
its warnings in the server log rather than this array. Refusals are errors and write nothing: no write
or read permission on any existing note it touches (an unreadable note answers like a missing one and
its hash is never returned), a stale `prev_hash` (every stale note is named in `details.stale`), a page that
already covers the topic (`conflict`, `reason: duplicate_page`, checked again right before the write;
`allow_duplicate: true` overrides), text that fails the poison scan, a heading that is missing or
ambiguous, and two entries naming one filesystem object (existing paths are compared by device and
inode, so symlink aliases collide while two real case-distinct files on a case-sensitive volume do not).
Open contradictions the detector
already flagged on a touched note are listed in `contradictions`; new ones are found by the indexer
afterwards.

**Confirmation.** Per operation, as the single-note tools ask it. Creating a page inside the wiki folder
needs **no confirmation**: every existing note a commit patches or replaces is snapshotted first, so
`restore_note` undoes those. A new page has no prior state, so it has no snapshot and `restore_note`
cannot undo it; remove it with `delete_note` (which asks for confirmation, and moves the page to the
trash). Patching a related note anywhere asks nothing either, as `patch_note` does, under the same ACL (both
read and write permission on the note). Overwriting an existing non-empty page (`page.mode: overwrite`,
which needs `prev_hash`) asks for confirmation exactly like `write_note`. Everything else keeps its
existing rules: `write_note`, `patch_note`, `delete_note` and the rest behave as before.

**All or nothing on errors; not crash-atomic.** Before the first write, `commit_wiki_page` checks the
read and write ACL of every path, the `prev_hash` of every existing note, the poison and memory-defense
scans, and computes every resulting note. It then snapshots every existing note it will replace, stages
a synced temp file for every note, writes one `pending` write-provenance record naming every path and the
hash it is about to hold, and renames the files back to back, re-hashing each existing note immediately
before it is replaced: a note edited since it was read aborts the whole batch and the edit is kept. If a
pending provenance row cannot be recorded, the staged files are discarded and no rename runs. The
settling `ok` record uses the batch's own written hashes, not a disk re-read that could observe a later
concurrent edit. If a
write fails part way, every earlier write is undone, except a note whose content changed since the batch
wrote it, which is left alone and named in `details.changed_since_written`; a page someone else created
is never deleted. Each undo moves the note aside, hashes the moved file and only then drops it or puts
the old text back (with a no-replace create), so it never deletes or overwrites what the batch did not
write; while a note is aside its name is briefly empty, and a note another process writes there in that
gap is kept. When any undo is incomplete (`internal_error`, `details.reason: rollback_incomplete`) the
snapshots taken for the call are kept, so `restore_note` can recover each pre-image; after a clean
rollback they are dropped. Snapshot retention is pruned only after the batch succeeds, and that
cleanup, like reindexing, is best-effort: a fault there (a locked database, say) cannot undo a batch
that has landed, so it is logged and returned as a `post_commit` problem, never as an error. When the
provenance frontmatter stamp is on, the new page is checked against `SCHEMA.md` with the stamp in
it. A process crash (SIGKILL,
power loss) between two renames can leave a partial batch: the `pending` record then has no `ok` or
`error` record after it, which is how the batch is found, and `restore_note` returns each replaced note.
The re-hash narrows the window for an edit by another process to the gap between the hash and the
rename; POSIX has no conditional rename, so it cannot be closed. A successful commit ends with an `ok`
record listing every touched path; an aborted one ends with an `error` record only when the `pending`
record was already written.

### Generated index and log pages

The wiki folder also holds two files the server writes, not you and not an LLM. Both start with
`generated_by: reliquary-tc` in their frontmatter and a notice; do not edit them.

* **`index.md`**: every page of the wiki folder grouped by its `SCHEMA.md` `type` (the schema's order&#x20;
  first, then other types, then `(no type)`), one link each. Queued after every `commit_wiki_page` and,
  with `maintenance.wikiPages.enabled: true`, every `maintenance.wikiPages.intervalHours` (default 6). It
  is never maintained by an LLM and is left unchanged when the listing did not change.
* **`log.md`**: an append-only projection of the write provenance chain for the wiki folder, one line per&#x20;
  change: `time (UTC) | op | path | principal | model | tool#seq`, for example
  `2026-10-02T09:15:00Z | create | wiki/concepts/Spaced repetition.md | alice | claude-opus | commit_wiki_page#41`.&#x20;
  `op` is `create`, `update` or `delete`. The last projected provenance sequence number is stored in
  the file's `last_seq` frontmatter, so a re-run never repeats a line. It lags one write: a commit's own
  line appears the next time the pages are regenerated. `model` is what the client said about itself.
  **Reading it needs `read:provenance` as well as `read:notes`**, the scope `get_provenance` requires for the
  same facts. The server enforces that on the path itself (an implicit per-path rule-scope, added to the
  ACL of every vault with a `wiki.folder`), so `read_note`, the search and listing tools, links, resources
  and `lint_wiki` all refuse or omit `log.md` for a caller without it. The same scope is needed to edit or
  delete the file; the server's own regeneration is not a caller and is not affected.&#x20;

Both list only paths a reader holding no rule-scope may read under the vault's ACL (a symlink alias of a
read-denied folder included) and never an Excluded note, so a page in a read-denied folder is not named.
A page name is written with control, format and line-separator characters stripped, so one page is one
line. They are written with no confirmation, inside the
wiki folder only, with a snapshot of what they replace, and a failure is reported as a
server error-log warning, never an error on the already committed write. The queue keeps generation
off the request path because a large vault scan can take seconds.

**A hand-edited page is never overwritten.** A keyed HMAC-SHA-256 in the frontmatter seals each file;
the per-server key is created on first use in a mode-0600 file under the server cache directory, and
the seal also binds the vault id and file path. If the file was edited, or is someone's own `index.md`&#x20;
with no marker, the server leaves it as it is, logs the warning,
and `lint_wiki` (check `generated_pages`) proposes the fix: move
your text to a page of its own and delete the file (`restore_note` keeps a copy); the next pass writes a
fresh one. An edit made while a page is being rebuilt is caught too (the file is hashed again right
before it is replaced); like `commit_wiki_page`, this cannot close the gap between that hash and the
rename, because POSIX has no conditional rename. Duplicate-topic detection, `lint_wiki` and the orphan, dangling-link and provenance scans skip
both files, and their links are not counted as inbound links.

The seal key is server state. Pointing the server at a new `cacheDir`, or running another server with
its own cache state, gives it a different key, so existing generated pages read as edited rather than
trusted. Delete the affected `index.md` or `log.md`; the next wiki-page pass regenerates it with that&#x20;
server's key.

**One-time migration from the old seal.** A matching legacy unkeyed SHA-256 is recognised only so the
server can replace the file; it is never accepted as authenticated input. The next pass rebuilds the
whole page with the HMAC. For `log.md`, it discards the legacy preamble and `last_seq` and projects from
the provenance database again. An edited or invalid legacy file is left untouched and reported.

## Long-running tools

Some clients give up on a call after about a minute (Codex and ChatGPT around 60 s, the Cloudflare
Agents SDK 60 s), and Claude Code after five minutes without progress. A tool that can outlast that,
today `index_vault` on a large vault, therefore never holds the request open past a time budget of
**40 seconds**:

* **It finishes inside the budget.** The call returns the tool's own result, exactly as if it had run
  inline. This is the common case, so small calls stay synchronous.
* **It does not.** The call returns a normal (non-error) result carrying a handle,
  `{ "status": "working", "task_id": "…", "poll_tool": "get_task_status", "tool": "index_vault", "message": "…" }`.
  The work keeps running on the server. Call `get_task_status` with that `task_id`: while it is
  `working` it reports `progress` (units done, total when known) and a `retry_after_seconds` hint, and
  once `completed` it carries the tool's result under `result` (a failure carries `error`). The text
  block says the same in a sentence, because some clients read nothing else.
* **A client that declared the Tasks extension** gets the handle at once and polls `tasks/get` (HTTP).
  stdio has no `tasks/get` route, so it neither advertises the extension nor hands a task handle to a
  client that declares it: it gets the budgeted wait and `get_task_status` like any other client.
* **A caller that sends a `progressToken`** receives `notifications/progress` while the call runs;
  `index_vault` reports notes processed out of notes seen. Most clients reset their own timeout on each
  one.

To stop a task, call `cancel_task` with the same `task_id` (clients that declared the Tasks extension
use `tasks/cancel` instead). Cancellation is cooperative: the call returns the task's status right
after the request, which may still be `working`, and `get_task_status` then shows it end as
`cancelled`. A task that already finished is returned unchanged, with its result.

Only the caller that started a task can read or cancel it; a missing, foreign or internal
id all answer `not_found`. The same budget applies when the tool is reached through `call_capability`
or a domain tool.

## Result size and paging

Clients cap how much of a tool result they show the model: Grok Build inlines about 20 KB and
drops `resource_link` blocks, claude.ai keeps about 150,000 characters, and Claude Code saves a
text result over 50,000 characters to a file. So a **list or search tool's default page stays
under 20 KB** on a large vault. It does that by lowering the default item count, never by cutting
a result mid-item, and every one of them says how to get the rest. `governor.maxResponseBytes`
is unchanged: it is the hard ceiling that refuses an oversized response, not a page size.

| Tool | Default page | Next page |
| - | - | - |
| `list_notes`, `list_attachments` | 100 | `next_cursor` |
| `find_notes_by_tag`, `find_notes_by_property`, `get_backlinks`, `find_orphans`, `find_unresolved_links` | 100 | `next_cursor` (an offset; pass it as `cursor` with the same arguments) |
| `search_text`, `search_regex`, `search_jsonlogic`, `search_vault`, `list_tasks` | 25 | `next_cursor` |
| `find_link_cycles` | 10 cycles of at least `min_length` (3) and at most `max_length` (10) links; `skipped_shorter` and `skipped_longer` count the rest, and `total` counts every cycle found (`truncated` marks a lower bound) | raise `limit`, lower `min_length`, or raise `max_length` |
| `vault_graph_search`, `knowledge_search`, `diagnose_retrieval` | `final_top_k` 10 | raise `final_top_k` |
| `list_commands`, `makemd_query`, `query_datacore`, `search_omnisearch`, `knowledge_get_critical`, `list_capture_queue`, `get_session_traces`, `query_base` | 50 to 100 | `cursor` where the tool has one, else a larger `limit` |

Pass `limit` to ask for a bigger or smaller page. The whole-note readers (`read_note`,
`read_notes`, `read_resources`, `read_snapshot`, `fetch`, `search_and_read`, `bundle_files`,
`bundle_folder`, `get_active_file`, `session_bootstrap`) exist to return whole notes, so they are
paged by the byte budget instead, and they advertise
`_meta["anthropic/maxResultSizeChars"]` in `tools/list` so Claude Code keeps their result inline
rather than saving it to a file. The value is `governor.maxResponseBytes`, capped at Claude Code's
own 500,000-character ceiling, and no other tool carries it.

No tool returns a `resource_link` or an embedded resource, and every result carries a text block.
`get_attachment` returns a `description` (type, pixel size for common images, file size, and a
pointer to `ocr_attachment`) beside the base64 `content`; pass `include_content: false` for the
description alone.

## Response format

Tools that return more than an acknowledgement take an optional `response_format`:
`concise` returns only the high-signal fields, `detailed` returns the full payload.
The format is resolved in this order: an explicit `response_format` on the call, then
the legacy `verbosity` alias (`terse` is `concise`, `full` is `detailed`), then the
operator default `tools.defaults.responseFormat`, then `detailed`. The shipped default
is `detailed`, so output is unchanged until a call or the config opts in.

Supported today: `read_note`, `read_notes`, `get_active_file`, `write_note`, `append_note`,
`patch_note`, `update_frontmatter` (and the `update_active_file`, `append_active_file` and
`patch_active_file` tools, which pass the parameter to the tool they delegate to),
`read_frontmatter`, `find_notes_by_property`, `list_notes`, `get_outgoing_links`,
`get_backlinks`, `find_unresolved_links`, `read_resources`, the search tools
(`search_text`, `search_regex`, `search_semantic`, `search_jsonlogic`, `search_vault`) and
`note_quality_report`. A concise write acknowledgement is `{ vault, path, content_hash }`;
a concise `read_note` is the note body without frontmatter (or just the requested section).
Other concise shapes: `read_frontmatter` omits `has_frontmatter` (it is `frontmatter !== null`);
`list_notes` returns `{ vault, notes: [{ path }], next_cursor }`; `get_backlinks` returns
`{ source_path, line }` per backlink; `get_outgoing_links` returns `{ target, line, resolved }`
per link plus `heading`, `target_path` and `candidates` when they are set; `read_resources`
returns `{ ok, uri, text }` per item with the note body only.

Note resources (`reliquary-tc://<vault>/<path>`) name their vault in the URI. A trusted (stdio) caller
can read any registered vault it may read, under that vault's own folder ACL, and a refusal in
another vault answers as a missing note. Set `resources.boundVaultOnly: true` to keep them on the
default vault ([configuration](https://docs.the40thieves.dev/reliquary-tc/configuration/config-yaml.md)). A vault-bound HTTP token stays on its
own vault either way.

`resources/read` takes no parameters, so only the config default applies to it: with
`tools.defaults.responseFormat: "concise"` it returns the note body without its frontmatter
block (the URI and MIME type are kept). The scope, vault binding, folder ACL, size ceiling
(judged on the raw note) and cache hints are the same in both formats. `find_orphans` already
returns bare paths, so it takes no parameter.

The listing, graph, memory and episode tools also take it: `list_attachments`,
`list_periodic_notes`, `list_snapshots`, `list_capture_queue`, `list_goals`, `search_and_read`,
`vault_graph_search`, `knowledge_search`, `get_entity`, `query_entity_graph`,
`get_session_traces`, `session_bootstrap`, `work_episodes`, `work_episode_chain`,
`work_search`, `gap_report`, `rewrite_link` and `prune_hub_links`. Their concise shapes keep
what a caller acts on and drop the rest:

* `list_attachments` returns `{ path }` per file plus `reference_count` when requested (no size,
  mtime, MIME type, folder echoes or `total_returned`); `list_periodic_notes` returns
  `{ date, path }` per item (no period or mtime); `list_snapshots` returns `{ id, op, created_at }`
  per snapshot (no `content_hash`, size or total); `list_goals` returns `{ id, text, status }`
  plus `target_date` and `closed_at` when set.
* `search_and_read` returns `{ path, rank, score, body, content_hash }` per note, without
  frontmatter (note mode) or `chunk_id` (section mode). `size_bytes` and `truncated` appear only on
  a note that was cut to its share, since there they say how much to fetch with `read_note`.
* `vault_graph_search` and `knowledge_search` keep `chunk_id`, `path`, `content`, `rerank_score`,
  `vault` and `changed_since_d` per hit, and drop the retrieval provenance (arm, hop, edge, seed)
  and the `route` and `coverage` blocks. `vault_graph_search` also keeps `mode_used`,
  `failed_variants` and `failed_vaults`.
* `get_entity` and `query_entity_graph` return each observation as `{ text, key }`, plus
  `valid_to` and `superseded_by` when the fact is no longer current; they omit `valid_from`,
  `created_at`, `updated_at`, `as_of`, the hop-by-hop `path` and a null `vault_path`.
* `list_capture_queue` omits null and empty item fields; `get_session_traces` drops `args_hash` and
  `caller`; `session_bootstrap` drops each loaded note's parsed frontmatter (the note text in
  `content` is whole).
* `work_episodes`, `work_episode_chain` and `work_search` keep id, time, session, tool, status,
  error code, summary, `trust`, `eligibility`, a true `blocked` and the amendment link, and drop
  vault, caller, channel, episode type, duration, result size and every null or empty field.
  `gap_report` keeps `{ id, query, top_score, gap }` per query (no `results` or `nearest`) and the
  totals.
* `rewrite_link` and `prune_hub_links` on a real run return the counts (`notes_changed`,
  `links_rewritten`, `removed_count`) and `content_hash` without the per-note change list,
  `removed[]` and `prev_hash`. A dry run keeps them, because they are the preview and the inputs
  of the confirming call.

The knowledge-read, link-health, bundle and canvas-reader tools also take it: `vault_context`,
`explain_answer`, `diagnose_retrieval`, `knowledge_get_critical`, `audit_provenance`,
`vault_health_score`, `suggest_links`, `suggest_tags`, `bundle_files`, `bundle_folder` and
`read_canvas` (and `get_provenance`, which drops the host, the full path list, the record hash and
the machine field).

* `vault_context` keeps the packed notes with `{ chunk_id, content, score }` per chunk, the
  syntheses, the open contradictions, the lessons as `{ chunk_id, path, excerpt }`, the episodes,
  `diff_since` and the prefetch pair; it drops the route signals, the query source, the budget and
  stats blocks, and each chunk's `source` and `hop`.
* `explain_answer` keeps each link's chunk, path, whether the chunk still resolves, the citation
  verdict and score and the correlation, plus `caveat` and `citation_pass` (they stop an unjudged
  chain reading as an unused one); it drops `summary` and each link's retrieval echo.
  `diagnose_retrieval` returns `{ vault, returned, dropped_at, summary }`.
  `knowledge_get_critical` returns `{ path, title, category, source }` per document.
* `audit_provenance` drops the `field` echo, `with_provenance` and the `by_folder` breakdown;
  `vault_health_score` drops `total_links` and the per-penalty `breakdown`; `suggest_links`
  returns `{ path, score }` per suggestion; `suggest_tags` returns `source` and the suggestions.
* `bundle_files` and `bundle_folder` keep the bundle text, `file_count`, `truncated` and (per
  tool) the resume `cursor` or `missing_paths`; they drop the per-file list (each path already
  heads its block in the bundle), `total_bytes` and the `root` echo. `read_canvas` keeps what a
  node says and what an edge joins, and drops the layout (geometry, background, edge sides and
  ends) and the two counts.

Ten more reads and reports take it: `find_notes_by_tag`, `get_note_tags`, `read_property`,
`get_periodic_note`, `find_or_create_periodic_note`, `index_vault`, `inspect_visibility`,
`get_server_config`, `bulk_create_notes` and `bulk_set_property`.

* `find_notes_by_tag` returns `{ path }` per match plus `truncated` (it says the list is cut), and
  drops the matched tags and `total`; `get_note_tags` returns only the combined `all` set, not the
  frontmatter and inline split; `read_property` returns `value` and `found` without the `key` and
  `nested` echoes.
* `get_periodic_note` and `find_or_create_periodic_note` keep the date, path, `exists` or
  `created`, the note `content` and any `redactions`, and drop the `period` echo and the parsed
  `frontmatter` (the content already carries the block).
* `index_vault` keeps the note and chunk totals and every failure, skip and degradation signal
  (`secrets_skipped`, `notes_embed_failed`, `chunks_dedup_unresolved`, `embed_batch_rejections`,
  `notes_stale_skipped`, `notes_epoch_stale_skipped`, `notes_frontmatter_failed` with its list, `vec_enabled`, `fts_enabled`),
  and drops the bookkeeping counters (unchanged chunks, edge and upsert/delete totals, reused
  dedup chunks, model, dimensions).
* `inspect_visibility` returns `{ name, visibility, reason }` per tool, plus `matched_tag` and
  `missing_scopes` when the verdict has one (the rule that decided it); it drops `domain`,
  `required_scopes` and `tags`. The `summary` still covers the whole surface.
  `get_server_config` keeps the auth mode, `read_only`, the embeddings provider, the limits, the
  limiter backend and failure policy, the governor ceiling and the detected plugins, and drops the
  per-class throttle tiers, the observability toggles and the retrieval-defaults report.
* `bulk_create_notes` and `bulk_set_property` keep `succeeded`, `failed` and every per-item
  outcome (path, `ok`, hash, `prev_value`, `redactions`, error), and drop `processed`,
  `duration_ms` and each created item's `mode_used`.

Concise never drops a safety signal: a non-empty `quality_warning`, a `poison_assessment`
other than `none` (`list_capture_queue` always keeps it), `redactions`, a redacted `to_target`
echo from `rewrite_link`, the trust and eligibility of a work episode, and a `patch_note` call's
removed-line and removed-byte counts are kept, and errors are never shaped. Because `concise`
omits fields, the advertised output schema marks those fields optional; a `detailed` result
always carries them.

### Tools with no `response_format`

Each of these was reviewed and takes no parameter, because there is nothing a caller could spare:

| Tool | Why |
| - | - |
| `list_tags`, `list_properties` | One `{ name, count }`-style row per entry: already minimal. |
| `search`, `fetch` | The shape is fixed by the connector contract that ChatGPT deep research and company knowledge read: `{ results: [{ id, title, url, text }] }` and `{ id, title, text, url, metadata }`. The full note text is the payload. |
| `list_vaults`, `list_kanban_boards` | One minimal row per entry. |
| `list_workspaces` | Workspace names only. |
| `list_bookmarks` | The item tree and the compare-and-swap `content_hash` are the payload. |
| `list_commands`, `list_quickadd_actions`, `list_templates` | Minimal `{ id, name }`, `{ name, type }` or ACL-filtered `{ path, name }` rows. |
| `list_tasks` | Every field is task data, and empty optional fields are already omitted. |
| `list_contradictions` | The rationale is the product. |
| `episode_stats` | Aggregate counts only. |
| `find_orphans` | Bare paths already. |
| `commit_wiki_page` | A short receipt of the writes plus the problems found: every field is a safety signal. |
| `plur_get`, `plur_recall`, `plur_recall_hybrid`, `plur_similarity_search` | Read-only proxies of an external payload this server does not own. |
| `reflect`, `knowledge_challenge` | The synthesized answer or verdict and its evidence are the product; the rest is a few short fields. |
| `find_link_cycles`, `graph_centrality`, `graph_path_between` | The path lists, ranked rows or hop chain are the payload; the rest is a count or a presence flag. |
| `get_link_strength` | One scored row: every field is a component of the score. |
| `graph_communities` | The communities are the payload; `modularity`, `meaningful` and the chance warning are safety signals. |
| `git_status`, `git_diff`, `git_log`, `git_stage`, `git_commit` | Fixed status, diff, log or acknowledgement fields. `git_commit` also returns any `stamped_trailers`, which are provenance a caller must see. |
| `ocr_attachment`, `ocr_bulk` | Fixed extracted text, cache/duration fields, and per-file batch results. |
| `read_base`, `query_base`, `read_kanban_board`, `query_canvas` | The parsed document, resolved rows, columns and cards or matching nodes are the payload; `content_hash` is the compare-and-swap token. |
| `create_base`, `update_base`, `create_canvas`, `update_canvas`, `add_kanban_card`, `move_kanban_card` | Write acknowledgements: counts, any deprecation notice and the compare-and-swap hashes the next write needs. |
| `read_excalidraw`, `create_excalidraw`, `update_excalidraw` | Fixed filesystem parse or companion text fields, and fixed write acknowledgements. |
| `format_table`, `insert_table_column`, `insert_table_row`, `sort_table_by_column` | Write acknowledgements: row and column counts, the compare-and-swap hashes and the `redactions` signal. |
| `eval_dataview_field`, `validate_dql`, `search_dql` | Dataview values, validity/errors, or rows; opaque values have nested paths ACL-checked, and `search_dql` returns indexing `note_paths`. |
| `query_datacore`, `makemd_query`, `search_omnisearch`, `tasks_filter` | ACL-filtered `items` and their recomputed `total`. |
| `makemd_list_spaces` | The spaces array only, with nested paths ACL-checked. |
| `remotely_save_status`, `remotely_save_trigger` | Fixed sync status or trigger acknowledgement fields. |
| `create_entity`, `add_observation`, `update_observation`, `link_entities`, `unlink_entities`, `rename_entity`, `delete_entity` | Write acknowledgements: entity and observation ids, status, the edge identity, counts (observations, relations removed, neighbours re-materialized), timestamps and the `redactions` signal. |
| `start_session`, `end_session`, `enqueue_capture`, `commit_capture` | Write acknowledgements: ids, paths, event count and duration, the compare-and-swap hash and the `redactions` signal. |
| `set_goal`, `close_goal`, `record_retrieval_feedback`, `work_result`, `work_forget` | Write acknowledgements: ids, the new state and how many retrievals were stamped, demoted or forgotten (`updated: 0` carries a `reason`). The batch form of `record_retrieval_feedback` (`verdicts`, 1 to 50 items, one transaction) returns `results`: one `{chunk_id, updated, reason?}` per item. |
| `session_rerun` | The per-record verdicts and divergences are the report; the summary counts qualify them. |
| `add_tag`, `remove_tag` | Write acknowledgements: the removed count and the compare-and-swap hashes the next write needs. |
| `copy_note`, `move_note`, `delete_note`, `delete_active_file`, `restore_note`, `snapshot_note` | Write acknowledgements: the destination or snapshot id, the content hashes, where a deleted or overwritten file was trashed, `backlinks_updated` (a blast-radius count) and the `redactions` signal. |
| `bulk_move_notes` | Every per-move row is a blast-radius count or an error, and `hidden_backlinks` is a safety flag. |
| `note_exists` | One boolean and a type. |
| `read_snapshot` | The stored content is the payload; the rest is four short scalars. |
| `read_metadata_fields`, `resolve_daily_note` | Fixed metadata and daily-note fields; nested metadata paths and the resolved daily-note path are ACL-checked. |
| `execute_command`, `execute_template`, `trigger_quickadd`, `show_file_in_obsidian` | Fixed action acknowledgements. `execute_template` also returns server-generated provenance status when present. |
| `get_attachment` | The base64 bytes are the payload; MIME type, size and encoding describe them. |
| `write_attachment`, `move_attachment`, `delete_attachment` | Write acknowledgements: the path, size and hash, where a replaced or deleted file was trashed, `references_updated` (a blast-radius count) and, for a delete, the notes that still reference it. |
| `add_bookmark`, `remove_bookmark`, `open_workspace`, `save_workspace` | Write acknowledgements, or the layout itself for `open_workspace`: counts and the compare-and-swap hash the next write needs. |
| `create_periodic_note`, `append_to_periodic_note` | Write acknowledgements: the path, the bytes appended, whether the template expanded and the `redactions` signal. |
| `update_task` | Write acknowledgement: the before and after task state, the compare-and-swap hash and the `redactions` signal. |
| `generate_uri` | One URI. |
| `add_vault`, `reload_vault`, `reset_vault_cache`, `refresh_plugin_capabilities` | Acknowledgements: the vault id and times, the rows dropped (the blast radius) or the capability diff, which is the payload. |
| `get_vault` | One vault's configuration; `read_only` and the ACL path lists are safety signals and the rest is two short blocks. |
| `get_index_status`, `get_task_status`, `server_health` | Every field is a health signal (reconcile state, write failures, vec and fts, the job queue, leader role, facade and telemetry; for `get_task_status`, the state, progress and retry hint of one task, with the finished tool's own result under `result`). |
| `get_metrics`, `inspect_acl` | The metric rows, or the one allow or deny verdict with its rule, are the payload. |

Every registered tool is in exactly one of the two groups, the tools that take `response_format`
and the table above. A test fails when a newly registered tool is in neither, so the decision
cannot be skipped.

## Degradation & errors

A tool that needs an unavailable capability (a missing plugin, an unconfigured
embedding provider) returns a typed error from the shared `ReliquaryTcError`
taxonomy (e.g. `plugin_missing`, `embedding_provider_error`) with a `retryable`
flag and a bounded `recovery` hint naming the next step — it never throws an
opaque failure. At the MCP boundary a dispatch failure
surfaces as a **Tool Execution Error** (`isError: true` with human-readable text
plus the structured error as `structuredContent`), so a model can self-correct
rather than seeing a protocol error.

> [!NOTE]
>
> Per-tool reference pages auto-generated from the live `ToolRegistry` and its Zod
> schemas are a deferred follow-up. This page is the curated overview.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.