@appsoftwareltd/etherpk-mcp 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/main.js CHANGED
@@ -713,7 +713,7 @@ function looksLikeAgentSetupCode(value) {
713
713
  }
714
714
  var package_default = {
715
715
  name: "@appsoftwareltd/etherpk-mcp",
716
- version: "0.17.1",
716
+ version: "0.18.0",
717
717
  license: "Elastic-2.0",
718
718
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
719
719
  type: "module",
@@ -3896,7 +3896,8 @@ function frontmatterLines(lines) {
3896
3896
  for (let i = 1; i < lines.length; i++) if (DELIMITER.test(lines[i])) return i + 1;
3897
3897
  return 0;
3898
3898
  }
3899
- " ".repeat(2);
3899
+ /** The Indent Unit as text - what Tab inserts. */
3900
+ var INDENT = " ".repeat(2);
3900
3901
  /** Width of the `- ` marker, which sets a bullet's content column (`indent + MARKER_WIDTH`). */
3901
3902
  var MARKER_WIDTH = 2;
3902
3903
  /** A tab advances to the next multiple of this column, as CommonMark reads it. */
@@ -4129,7 +4130,7 @@ function isBullet(line) {
4129
4130
  return /^-\s/.test(line.trimStart());
4130
4131
  }
4131
4132
  /** A bullet whose content is `[ ]` / `[x]` is a task; returns its done state. */
4132
- function taskDone(line) {
4133
+ function taskDone$1(line) {
4133
4134
  const m = /^-\s+\[([ xX])\]/.exec(line.trimStart());
4134
4135
  if (!m) return void 0;
4135
4136
  return m[1].toLowerCase() === "x";
@@ -4183,7 +4184,7 @@ function parseBlocks(markdown) {
4183
4184
  }
4184
4185
  if (isBullet(lines[i])) {
4185
4186
  const contentCol = indentOf(lines[i]) + 2;
4186
- const done = taskDone(lines[i]);
4187
+ const done = taskDone$1(lines[i]);
4187
4188
  const start = i;
4188
4189
  const buf = [];
4189
4190
  i = take(i, buf);
@@ -4498,6 +4499,7 @@ var FREE_TAG_WORD = /^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/;
4498
4499
  * person who wrote them meant one, so neither is a Free Tag either.
4499
4500
  */
4500
4501
  var TASK_TAG_SHAPED = /^(?:P\d+|W|D|T|C|A|[DCS]-[\d-]*)$/i;
4502
+ /** Whether `word` (without its `#`) can be a [[Free Tag]]: what the Task Editor checks a new tag by. */
4501
4503
  function isFreeTagWord(word) {
4502
4504
  return FREE_TAG_WORD.test(word) && /[A-Za-z]/.test(word) && !TASK_TAG_SHAPED.test(word);
4503
4505
  }
@@ -4544,11 +4546,13 @@ function freeTagsIn(text) {
4544
4546
  /**
4545
4547
  * The text with its Free Tags taken out, each with the whitespace before it (after it, at the
4546
4548
  * start), so `Fix the gate #bug.` reads `Fix the gate.`. Empty when the text is only Free Tags.
4549
+ * `which` keeps the tags it says no to: the Task Editor takes out one tag and leaves the rest.
4547
4550
  */
4548
- function withoutFreeTags(text) {
4551
+ function withoutFreeTags(text, which = () => true) {
4549
4552
  let out = "";
4550
4553
  let at = 0;
4551
- for (const { from, to } of freeTagMatches(text)) {
4554
+ for (const { word, from, to } of freeTagMatches(text)) {
4555
+ if (!which(word)) continue;
4552
4556
  const before = text.slice(at, from);
4553
4557
  out += from === 0 ? "" : before.trimEnd();
4554
4558
  at = to;
@@ -4673,6 +4677,7 @@ function withStatus(tags, status) {
4673
4677
  function sameTags(a, b) {
4674
4678
  return a.priority === b.priority && STATE_TAGS.every(([state]) => a[state] === b[state]) && a.due === b.due && a.scheduled === b.scheduled && a.completion === b.completion;
4675
4679
  }
4680
+ new Set(STATE_TAGS.map(([kind]) => kind));
4676
4681
  // ../client/src/lib/document/index-derive.ts
4677
4682
  /**
4678
4683
  * The pure index-derivation layer (Dual Mode Editor.md → The derived index store).
@@ -10111,6 +10116,62 @@ function renamedFavourite(entry, target) {
10111
10116
  concept: to
10112
10117
  };
10113
10118
  }
10119
+ /** The concept keys of `names`, trimmed and lower-cased, blanks left out. */
10120
+ function nameKeys(names) {
10121
+ return new Set(names.map((name) => name.trim().toLowerCase()).filter((key) => key !== ""));
10122
+ }
10123
+ /**
10124
+ * Whether a stored favourite is a document favourite for one of `keys`. A View object, whatever
10125
+ * concept it is about, is not: it outlives the page (ADR 0036 §4, amended 2026-11-03).
10126
+ */
10127
+ function documentFavouriteIn(entry, keys) {
10128
+ return typeof entry === "string" && keys.has(entry.trim().toLowerCase());
10129
+ }
10130
+ /** `list` without the document favourites for `keys`, or null when it is not a list or none was in it. */
10131
+ function withoutDocumentFavourites(list, keys) {
10132
+ if (!Array.isArray(list)) return null;
10133
+ const kept = list.filter((entry) => !documentFavouriteIn(entry, keys));
10134
+ return kept.length === list.length ? null : kept;
10135
+ }
10136
+ /** Delete from one member's `bookmarks:` map each bookmark whose concept is one of `keys`. Whether any went. */
10137
+ function deleteBookmarksOn(map, keys) {
10138
+ let hit = false;
10139
+ for (const [id, value] of [...map.entries()]) {
10140
+ const concept = storedBookmarkConcept(value);
10141
+ if (typeof concept !== "string" || !keys.has(concept.trim().toLowerCase())) continue;
10142
+ map.delete(id);
10143
+ hit = true;
10144
+ }
10145
+ return hit;
10146
+ }
10147
+ /**
10148
+ * Remove a deleted document from one member's top-level type `name`, when it is one of their
10149
+ * lists: its document favourites from `favourites:`, the bookmarks into it from `bookmarks:`, and
10150
+ * its name from the record of the shared list in `memberFlags:`. Whether anything went.
10151
+ */
10152
+ function forgetDocumentInMemberType(doc, name, keys) {
10153
+ const kind = memberListName(name)?.kind;
10154
+ if (kind === "favourites") {
10155
+ const array = doc.getArray(name);
10156
+ const entries = array.toArray();
10157
+ let hit = false;
10158
+ for (let i = entries.length - 1; i >= 0; i--) {
10159
+ if (!documentFavouriteIn(entries[i], keys)) continue;
10160
+ array.delete(i, 1);
10161
+ hit = true;
10162
+ }
10163
+ return hit;
10164
+ }
10165
+ if (kind === "bookmarks") return deleteBookmarksOn(doc.getMap(name), keys);
10166
+ if (kind === "memberFlags") {
10167
+ const flags = doc.getMap(name);
10168
+ const seen = withoutDocumentFavourites(flags.get("sharedFavouritesSeen"), keys);
10169
+ if (!seen) return false;
10170
+ flags.set("sharedFavouritesSeen", seen);
10171
+ return true;
10172
+ }
10173
+ return false;
10174
+ }
10114
10175
  /**
10115
10176
  * What a stored favourite is compared by when the array is rewritten: the exact entry, a name in
10116
10177
  * its own case, so a rename that only changes the case is written, and an entry that cannot be
@@ -11315,21 +11376,33 @@ function createGraphSync(deps) {
11315
11376
  return [...concepts.values()];
11316
11377
  },
11317
11378
  removeBookmarksOn(concepts) {
11318
- const keys = new Set(concepts.map((concept) => concept.trim().toLowerCase()).filter((key) => key !== ""));
11379
+ const keys = nameKeys(concepts);
11319
11380
  const changed = [];
11320
11381
  if (keys.size === 0) return changed;
11321
11382
  root.doc.transact(() => {
11322
11383
  for (const name of [...root.doc.share.keys()]) {
11323
11384
  if (memberListName(name)?.kind !== "bookmarks") continue;
11324
- const map = root.doc.getMap(name);
11325
- let hit = false;
11326
- for (const [id, value] of [...map.entries()]) {
11327
- const concept = storedBookmarkConcept(value);
11328
- if (typeof concept !== "string" || !keys.has(concept.trim().toLowerCase())) continue;
11329
- map.delete(id);
11330
- hit = true;
11385
+ if (deleteBookmarksOn(root.doc.getMap(name), keys)) changed.push(name);
11386
+ }
11387
+ });
11388
+ return changed;
11389
+ },
11390
+ forgetDocumentInMemberLists(names) {
11391
+ const keys = nameKeys(names);
11392
+ const changed = [];
11393
+ if (keys.size === 0) return changed;
11394
+ root.doc.transact(() => {
11395
+ for (const name of [...root.doc.share.keys()]) if (forgetDocumentInMemberType(root.doc, name, keys)) changed.push(name);
11396
+ const settings = metaMap.get("settings");
11397
+ if (typeof settings === "object" && settings !== null && !Array.isArray(settings)) {
11398
+ const shared = withoutDocumentFavourites(settings.favourites, keys);
11399
+ if (shared) {
11400
+ metaMap.set("settings", {
11401
+ ...settings,
11402
+ favourites: shared
11403
+ });
11404
+ changed.push("meta");
11331
11405
  }
11332
- if (hit) changed.push(name);
11333
11406
  }
11334
11407
  });
11335
11408
  return changed;
@@ -13977,6 +14050,28 @@ function lineIndent(line) {
13977
14050
  function isBulletLine(line) {
13978
14051
  return /^-\s/.test(line.trimStart());
13979
14052
  }
14053
+ /** A bullet whose content is `[ ]` / `[x]`; undefined if not a task. */
14054
+ function taskDone(line) {
14055
+ const m = /^-\s+\[([ xX])\]/.exec(line.trimStart());
14056
+ return m ? m[1].toLowerCase() === "x" : void 0;
14057
+ }
14058
+ /** Length of the bullet marker incl. its trailing space: `- ` (2) or `- [ ] ` (6). */
14059
+ function markerLength(line) {
14060
+ const indent = lineIndent(line);
14061
+ const rest = line.slice(indent);
14062
+ const task = /^-\s+\[[ xX]\]\s?/.exec(rest);
14063
+ if (task) return task[0].length;
14064
+ const bullet = /^-\s/.exec(rest);
14065
+ return bullet ? bullet[0].length : 0;
14066
+ }
14067
+ /** Offset of a line's content: past its indent and, on a bullet, past the `- ` / `- [ ] ` marker. */
14068
+ function contentStart(line) {
14069
+ return lineIndent(line) + markerLength(line);
14070
+ }
14071
+ /** The bullet's content (everything after the marker). `""` for an empty bullet. */
14072
+ function bulletContent(line) {
14073
+ return line.slice(contentStart(line));
14074
+ }
13980
14075
  /** A heading line (`#`…`######` + space), tolerant of leading indent — matches the block model. */
13981
14076
  function isHeadingLine(line) {
13982
14077
  return /^#{1,6}\s/.test(line.trimStart());
@@ -13998,11 +14093,11 @@ function fenceStartMap(blocks) {
13998
14093
  function branchRange(lines, i, blocks = fencedBlocks(lines)) {
13999
14094
  return {
14000
14095
  start: i,
14001
- end: branchEnd(lines, i, fenceStartMap(blocks))
14096
+ end: branchEnd$1(lines, i, fenceStartMap(blocks))
14002
14097
  };
14003
14098
  }
14004
14099
  /** The last line of the branch rooted at line `i` ({@link branchRange}), given the fence openers. */
14005
- function branchEnd(lines, i, starts) {
14100
+ function branchEnd$1(lines, i, starts) {
14006
14101
  const root = lineIndent(lines[i]);
14007
14102
  const own = starts.get(i);
14008
14103
  let end = own ? own.end : i;
@@ -16775,16 +16870,6 @@ function lastNonBlank(lines) {
16775
16870
  return -1;
16776
16871
  }
16777
16872
  // ../client/src/lib/agent-read/read-rules.ts
16778
- /**
16779
- * What an agent may read of a graph, and how much, for both readers that give a language model the
16780
- * graph's text: the [[Headless Client]]'s MCP tools (`apps/mcp/src/tools.ts`) and an [[Agent Chat]]
16781
- * in the browser (`documents-reader.ts`, ADR 0147). Kept in one place so the size caps, the test for
16782
- * protected text and the shape of a search or backlinks answer cannot drift between the two.
16783
- *
16784
- * The two differ in one rule, which each reader states for itself: the Headless Client lists a
16785
- * [[Protected Document]] by name, while an Agent Chat leaves it out entirely, because what it reads
16786
- * may be sent to a model provider.
16787
- */
16788
16873
  /** UTF-16 units of one document's text given before the rest is cut and the answer says so. */
16789
16874
  var READ_TEXT_CAP = 2e5;
16790
16875
  /** UTF-16 units across one bulk read before the rest is cut. */
@@ -16799,9 +16884,51 @@ function capText(text, cap = READ_TEXT_CAP) {
16799
16884
  truncated: false
16800
16885
  };
16801
16886
  }
16802
- /** Whether `text` is a Protected Document's: its whole body one encrypted fence. */
16803
- function isProtectedDocumentText(text) {
16804
- return documentProtection(text).kind === "document";
16887
+ /**
16888
+ * Whether `text` holds encrypted text anywhere: a Protected Document, or any other document with an
16889
+ * `etherpk-cipher` fence in it. The index flags both as protected (`index-db.ts`), and a reader whose
16890
+ * answers may leave the device treats both the same, which is the safer side.
16891
+ */
16892
+ function holdsEncryptedText(text) {
16893
+ return containsCipherFence(text);
16894
+ }
16895
+ /**
16896
+ * The keys of every name an agent is never shown: each the index flags protected, a page's own
16897
+ * name and each of its aliases, since the index sets the flag on both.
16898
+ */
16899
+ function protectedKeys(candidates) {
16900
+ return new Set(candidates.filter((candidate) => candidate.protected).map((candidate) => candidate.key));
16901
+ }
16902
+ /**
16903
+ * The [[Graph View]]'s link graph with every protected document taken out: its dot, every line in
16904
+ * or out of it, and any [[Pageless Concept]] it alone named (a protected page's title scopes), so
16905
+ * no ranking, path or list built on the answer can name one. The lines in go with the dot rather
16906
+ * than staying as lines to a name, which would make the page read as a Pageless Concept and invite
16907
+ * an agent to write a page that already exists. A route through a protected document is no route:
16908
+ * two concepts joined only through one are not shown joined. `hidden` adds keys the caller knows
16909
+ * to be protected that the answer has not flagged (an alias, a document flagged since).
16910
+ */
16911
+ function linkGraphWithoutProtected(graph, hidden = /* @__PURE__ */ new Set()) {
16912
+ const isHidden = (index) => {
16913
+ const concept = graph.concepts[index];
16914
+ return concept === void 0 || concept.protected === true || hidden.has(concept.key);
16915
+ };
16916
+ const links = graph.links.filter((link) => !isHidden(link.source) && !isHidden(link.target));
16917
+ const linked = new Set(links.flatMap((link) => [link.source, link.target]));
16918
+ const kept = graph.concepts.map((concept, index) => !isHidden(index) && (concept.kind !== "pageless" || linked.has(index)));
16919
+ const position = /* @__PURE__ */ new Map();
16920
+ return {
16921
+ concepts: graph.concepts.filter((_concept, index) => {
16922
+ if (!kept[index]) return false;
16923
+ position.set(index, position.size);
16924
+ return true;
16925
+ }),
16926
+ links: links.map((link) => ({
16927
+ ...link,
16928
+ source: position.get(link.source),
16929
+ target: position.get(link.target)
16930
+ }))
16931
+ };
16805
16932
  }
16806
16933
  /**
16807
16934
  * A page of the documents whose text matches `query`, as [[Search]] reads it: a `key:value` term
@@ -16891,6 +17018,20 @@ function isCalendarDay(value) {
16891
17018
  function shiftDate(date, days) {
16892
17019
  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
16893
17020
  }
17021
+ /** A new Date `months` after `date`, clamping the day to the target month's length. */
17022
+ function shiftMonth(date, months) {
17023
+ const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
17024
+ const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
17025
+ return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), lastDay));
17026
+ }
17027
+ Object.freeze({
17028
+ ArrowRight: (d) => shiftDate(d, 1),
17029
+ ArrowLeft: (d) => shiftDate(d, -1),
17030
+ ArrowDown: (d) => shiftDate(d, 7),
17031
+ ArrowUp: (d) => shiftDate(d, -7),
17032
+ PageDown: (d) => shiftMonth(d, 1),
17033
+ PageUp: (d) => shiftMonth(d, -1)
17034
+ });
16894
17035
  // ../client/src/lib/document/journal-concept.ts
16895
17036
  /**
16896
17037
  * What makes a [[Concept]] a [[Journal Concept]] — the one predicate that decides where a
@@ -18214,6 +18355,28 @@ async function taskLinesWith(lines, fingerprint) {
18214
18355
  }
18215
18356
  return out;
18216
18357
  }
18358
+ // ../client/src/lib/document/lane-reference.ts
18359
+ /** `/g/<graph>/k/<concept>#lane=<status>` or `/g/<graph>/kanban#lane=<status>`, the scheme before it optional. */
18360
+ var LANE_REFERENCE = /(?:etherpk:)?\/g\/([^/?#\s]+)\/(?:k\/([^?#\s]+?)|kanban)#lane=([a-z]+)(?![a-z])/;
18361
+ /**
18362
+ * The lane reference in `input`: the text as copied, or the `etherpk:` reference alone; null when
18363
+ * `input` holds none, or names a lane that is no task status.
18364
+ */
18365
+ function parseLaneReference(input) {
18366
+ const match = LANE_REFERENCE.exec(input);
18367
+ if (!match) return null;
18368
+ const [, graph, path, status] = match;
18369
+ if (!TASK_STATUSES.includes(status)) return null;
18370
+ try {
18371
+ return {
18372
+ graphId: decodeURIComponent(graph),
18373
+ concept: path === void 0 ? null : path.split("/").map(decodeURIComponent).join("/"),
18374
+ status
18375
+ };
18376
+ } catch {
18377
+ return null;
18378
+ }
18379
+ }
18217
18380
  // ../client/src/lib/document/templates/template-variables.ts
18218
18381
  /**
18219
18382
  * [[Template Variable]]s: the `{{name}}` text in a [[Template]] that is filled in when the
@@ -18639,8 +18802,9 @@ function minimalReplacement(text, next) {
18639
18802
  /**
18640
18803
  * Ticking a [[Task]] ticks every Task nested under it, archiving one archives them, and unticking
18641
18804
  * one unticks them, except a Cancelled or Archived one (CONTEXT.md → Task). The one statement of that rule: the checkbox click, the task
18642
- * toggle, the [[Tasks View]]'s tick, a [[Kanban Board]] move and the [[Headless Client]]'s
18643
- * `set_task` all ask this module which lines a write to a task brings with it.
18805
+ * toggle, the [[Tasks View]]'s tick, a [[Kanban Board]] move, the line menu's status rows, a state
18806
+ * tag that tidy on leave sets and the [[Headless Client]]'s `set_task` all ask this module which
18807
+ * lines a write to a task brings with it.
18644
18808
  *
18645
18809
  * The rule reads the [[Task Status]] either side of the write rather than the key that made it,
18646
18810
  * so every route agrees without knowing about the others:
@@ -18657,7 +18821,9 @@ function minimalReplacement(text, next) {
18657
18821
  *
18658
18822
  * Only those writes cascade, never typing: an edit to the line's text, the `#` [[Task Tag]] helper
18659
18823
  * included, changes that line alone, so taking `#C` off a ticked task by hand leaves the tasks under
18660
- * it as they are, as untyping a checkbox's `x` does.
18824
+ * it as they are, as untyping a checkbox's `x` does. A state tag typed later in the line is the one
18825
+ * exception: when the caret leaves the task, tidy on leave sets the status it names, as a status
18826
+ * write (`view/leave-tidy.ts`), and that write brings the nested tasks along like any other.
18661
18827
  *
18662
18828
  * Fenced code is read as the [[Derived Index]] reads it (`fencedBlocks`), so a line the index counts
18663
18829
  * as a task is one the cascade ticks, even where the editor's own parse draws it as code (under an
@@ -18696,11 +18862,12 @@ function moves(way, checkbox) {
18696
18862
  * makes each line Archived. Empty when the write neither makes the task Done or Archived nor
18697
18863
  * unticks it, and when no nested task needs changing.
18698
18864
  */
18699
- function nestedTaskWrites(lines, index, next, blocks = fencedBlocks(lines)) {
18865
+ function nestedTaskWrites(lines, index, next, blocks) {
18700
18866
  const way = direction(checkboxOf(lines[index]), checkboxOf(next));
18701
18867
  if (way === null) return [];
18702
- const inFence = linesInFencedBlocks(blocks);
18703
- const { end } = branchRange(lines, index, blocks);
18868
+ const fences = blocks ?? fencedBlocks(lines);
18869
+ const inFence = linesInFencedBlocks(fences);
18870
+ const { end } = branchRange(lines, index, fences);
18704
18871
  const writes = [];
18705
18872
  for (let i = index + 1; i <= end; i++) {
18706
18873
  if (inFence.has(i) || !moves(way, checkboxOf(lines[i]))) continue;
@@ -18737,6 +18904,159 @@ function lineWriteChanges(lines, writes) {
18737
18904
  }
18738
18905
  return changes;
18739
18906
  }
18907
+ // ../client/src/lib/document/task-structure.ts
18908
+ /**
18909
+ * The common task structure the [[Task Editor]] edits (ADR 0170), read from a [[Task]]'s lines and
18910
+ * written back as text.
18911
+ *
18912
+ * A task is its line and the [[Block]]s nested under it, and the structure is only a way of reading
18913
+ * them:
18914
+ *
18915
+ * - **Title**: the task's words, without its [[Task Tag]] run and its [[Free Tag]]s.
18916
+ * - **Lane, priority, due and scheduled dates and Free Tags**: read from the line by the task grammar
18917
+ * (`task-tags.ts`).
18918
+ * - **Assets**: every asset reference the task line and the lines nested under it show, fenced code
18919
+ * left out. One list for the Task Editor and the Headless Client's `read_task`.
18920
+ * - **Comments**: the children of the first bullet nested directly under the task whose words are
18921
+ * exactly `Comments`. Each child is one [[Task Comment]].
18922
+ * - **Description**: every child above the Comments bullet, or every child when there is none:
18923
+ * notes, images, nested tasks.
18924
+ * - **Additional context**: every child below the Comments block, written there by typing in the
18925
+ * document or by an agent. The split is by position only, so every line nested under the task is
18926
+ * in exactly one part, nothing in the text is ever lost to the structure, and the markdown stays
18927
+ * the truth an agent reads.
18928
+ *
18929
+ * Pure and DOM-free: the Client's Task Editor and the [[Headless Client]]'s `add_task_note` both
18930
+ * read and write through it, so a comment an agent adds lands where the editor shows it.
18931
+ */
18932
+ /** The words of the bullet that holds a task's [[Task Comment]]s. */
18933
+ var TASK_COMMENTS = "Comments";
18934
+ /** Every asset reference in a body: `../assets/<name>` at any depth, as markdown or HTML writes it. */
18935
+ var ASSET_REFS = /(?:\.\.\/)+assets\/[^\s)"'<>\]]+/g;
18936
+ /** Each asset reference in `body`, as often as it is written. */
18937
+ function assetReferencesIn(body) {
18938
+ return [...body.matchAll(ASSET_REFS)].map((match) => match[0]);
18939
+ }
18940
+ /**
18941
+ * The structure of the task on line `index`, or null when that line holds no task (or sits in fenced
18942
+ * code, where a task-shaped line is code).
18943
+ */
18944
+ function readTaskStructure(lines, index, blocks = fencedBlocks(lines)) {
18945
+ const inFence = linesInFencedBlocks(blocks);
18946
+ const parsed = index >= 0 && index < lines.length && !inFence.has(index) ? parseTaskLine(lines[index]) : null;
18947
+ if (!parsed) return null;
18948
+ const end = branchEnd(lines, index, blocks);
18949
+ const commentsLine = commentsBulletOf(lines, index, end, inFence, blocks);
18950
+ const comments = commentsLine === null ? null : {
18951
+ from: commentsLine + 1,
18952
+ to: branchEnd(lines, commentsLine, blocks)
18953
+ };
18954
+ const description = {
18955
+ from: index + 1,
18956
+ to: commentsLine ?? end
18957
+ };
18958
+ const additionalContext = comments !== null && comments.to < end ? {
18959
+ from: comments.to,
18960
+ to: end
18961
+ } : null;
18962
+ return {
18963
+ line: index,
18964
+ childIndent: " ".repeat(lineIndent(lines[index])) + INDENT,
18965
+ title: withoutFreeTags(parsed.text),
18966
+ status: taskStatus(parsed.done, parsed),
18967
+ priority: parsed.priority,
18968
+ freeTags: freeTagsIn(parsed.text),
18969
+ due: parsed.due,
18970
+ scheduled: parsed.scheduled,
18971
+ description,
18972
+ commentsLine,
18973
+ comments,
18974
+ additionalContext,
18975
+ end,
18976
+ assets: assetsShown(lines, {
18977
+ from: index,
18978
+ to: end
18979
+ }, inFence)
18980
+ };
18981
+ }
18982
+ /** The line after the branch rooted at line `index`. */
18983
+ function branchEnd(lines, index, blocks) {
18984
+ return branchRange(lines, index, blocks).end + 1;
18985
+ }
18986
+ /** The assets the span's lines show, once each, leaving out the lines in fenced code. */
18987
+ function assetsShown(lines, span, inFence) {
18988
+ const shown = lines.slice(span.from, span.to).filter((_, offset) => !inFence.has(span.from + offset));
18989
+ return [...new Set(assetReferencesIn(shown.join("\n")))];
18990
+ }
18991
+ /**
18992
+ * The first bullet nested directly under the task whose words are exactly `Comments`, or null. A
18993
+ * direct child is a bullet that no earlier child's branch holds; a task line is never one.
18994
+ */
18995
+ function commentsBulletOf(lines, task, end, inFence, blocks) {
18996
+ let at = task + 1;
18997
+ while (at < end) {
18998
+ const line = lines[at];
18999
+ if (inFence.has(at) || !isBulletLine(line)) {
19000
+ at++;
19001
+ continue;
19002
+ }
19003
+ if (taskDone(line) === void 0 && bulletContent(line).trim() === "Comments") return at;
19004
+ at = branchEnd(lines, at, blocks);
19005
+ }
19006
+ return null;
19007
+ }
19008
+ /**
19009
+ * The task's [[Task Comment]]s as text: each comment's words, with the lines nested under it moved to
19010
+ * the left margin as they are relative to it. Lines under the Comments bullet that are no bullet of
19011
+ * their own continue the comment before them.
19012
+ */
19013
+ function taskComments(lines, task) {
19014
+ if (!task.comments) return [];
19015
+ const margin = task.childIndent.length + INDENT.length;
19016
+ const comments = [];
19017
+ for (const line of lines.slice(task.comments.from, task.comments.to)) {
19018
+ if (lineIndent(line) === margin && isBulletLine(line) || comments.length === 0) comments.push([]);
19019
+ comments[comments.length - 1].push(line.slice(Math.min(margin, lineIndent(line))));
19020
+ }
19021
+ return comments.map((comment) => comment.join("\n").replace(/^-\s+/, ""));
19022
+ }
19023
+ /**
19024
+ * Text written as a [[Task Comment]]: a bullet whose later lines continue it, or bullets as they
19025
+ * are written. The result sits at the left margin, ready to be nested.
19026
+ */
19027
+ function asCommentBullet(text) {
19028
+ const written = text.trim();
19029
+ return written.startsWith("- ") ? written : `- ${written.replace(/\n/g, `\n${INDENT}`)}`;
19030
+ }
19031
+ /** The UTF-16 offset of the end of line `index`. */
19032
+ function lineEndOffset(lines, index) {
19033
+ let offset = 0;
19034
+ for (let i = 0; i <= index; i++) offset += lines[i].length + 1;
19035
+ return offset - 1;
19036
+ }
19037
+ /**
19038
+ * The change that adds `note` (bullets at the left margin, as {@link asCommentBullet} writes them) as
19039
+ * the last [[Task Comment]] of the task on line `index` of `text`: at the end of its Comments block,
19040
+ * above any additional context after it, or under a Comments bullet started as the task's last child
19041
+ * when it has none. `line` is the note's first line once
19042
+ * written. Null when the line holds no task.
19043
+ */
19044
+ function commentChange(text, index, note) {
19045
+ const lines = text.split("\n");
19046
+ const task = readTaskStructure(lines, index);
19047
+ if (!task) return null;
19048
+ const commentIndent = task.childIndent + INDENT;
19049
+ const nested = note.split("\n").map((noteLine) => noteLine === "" ? noteLine : commentIndent + noteLine);
19050
+ const after = task.comments ? task.comments.to - 1 : task.end - 1;
19051
+ const added = task.comments ? nested : [`${task.childIndent}- ${TASK_COMMENTS}`, ...nested];
19052
+ const at = lineEndOffset(lines, after);
19053
+ return {
19054
+ from: at,
19055
+ to: at,
19056
+ insert: `\n${added.join("\n")}`,
19057
+ line: after + 1 + (task.comments ? 0 : 1)
19058
+ };
19059
+ }
18740
19060
  // src/tools.ts
18741
19061
  /**
18742
19062
  * The eight tools an agent gets, as plain functions over an open {@link HeadlessGraph}. The MCP
@@ -18748,10 +19068,14 @@ function lineWriteChanges(lines, writes) {
18748
19068
  *
18749
19069
  * The rules (ADR 0072, [[2026-09-15 Headless Client And MCP]]):
18750
19070
  *
18751
- * - A [[Protected Document]] is listed by name and nothing else. Reading refuses; every write
18752
- * refuses, frontmatter included. The Headless Client never holds a Protection Key, so this is
18753
- * a courtesy to the agent rather than the guarantee - the guarantee is that there is nothing
18754
- * here to serve.
19071
+ * - A [[Protected Document]] is never shown, its name as well as its content (ADR 0072, amended
19072
+ * 2026-11-03): no listing, search, backlink, task or graph answer names one, and a read of one
19073
+ * answers as a read of a name nothing has. A name can say what the page was protected to hide,
19074
+ * and what an agent reads goes to its model provider; [[Agent Chat]] keeps the same rule
19075
+ * (`read-rules.ts`). A write that would land on one still refuses with `protected_document`,
19076
+ * since writing as if the name were free would make a second document under it - and that
19077
+ * tells the agent only that a name it already holds is taken. The Headless Client never holds
19078
+ * a Protection Key, so the content was never here to serve; the names are what this hides.
18755
19079
  * - Edits are anchored: `edit_document` replaces one exact, unique occurrence and lands as one
18756
19080
  * `applyChange` range, which the sync engine carries as one `Y.Text` change that merges with
18757
19081
  * whoever is typing elsewhere in the page. There is no whole-page replace.
@@ -18861,8 +19185,59 @@ async function liveText(graph, identity) {
18861
19185
  await graph.store.whenReady(identity.concept);
18862
19186
  return graph.store.open(identity.concept).getText();
18863
19187
  }
18864
- function refuseIfProtected(concept, text) {
18865
- if (isProtectedDocumentText(text)) throw new ToolError("protected_document", `"${concept}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be read or changed here - the user can unlock it in EtherPK.`);
19188
+ /**
19189
+ * The keys of every name an agent is never shown: those the index flags protected (a document whose
19190
+ * text holds an encrypted fence, and each of its aliases), and the aliases the store lists for such
19191
+ * a document, in case the index has not seen an alias yet. Read once per tool call.
19192
+ */
19193
+ function hiddenKeys(graph) {
19194
+ const keys = protectedKeys(graph.index.allConcepts());
19195
+ for (const doc of graph.store.listDocuments()) if (keys.has(doc.key)) for (const alias of doc.aliases) keys.add(conceptKey(alias));
19196
+ return keys;
19197
+ }
19198
+ /** Whether a document answers to a hidden name, by its title or any of its aliases. */
19199
+ function isHidden(keys, identity) {
19200
+ return keys.has(identity.key) || identity.aliases.some((alias) => keys.has(conceptKey(alias)));
19201
+ }
19202
+ /**
19203
+ * A document's live text when an agent may see it, or null when the document is hidden: flagged
19204
+ * by the index, or holding encrypted text the index has not caught up with yet.
19205
+ */
19206
+ async function visibleText(graph, identity, keys = hiddenKeys(graph)) {
19207
+ if (isHidden(keys, identity)) return null;
19208
+ const text = await liveText(graph, identity);
19209
+ return holdsEncryptedText(text) ? null : text;
19210
+ }
19211
+ /** The refusal for a name nothing in the graph has: also what a hidden document's name answers. */
19212
+ function notFound(asked) {
19213
+ return new ToolError("not_found", `No document is named "${asked}".`);
19214
+ }
19215
+ /** The document an agent asked to read, with its text, or `not_found` for a hidden one too. */
19216
+ async function requireReadable(graph, asked) {
19217
+ const identity = resolveIdentity(graph, asked);
19218
+ const text = identity ? await visibleText(graph, identity) : null;
19219
+ if (!identity || text === null) throw notFound(asked);
19220
+ return {
19221
+ identity,
19222
+ text
19223
+ };
19224
+ }
19225
+ /**
19226
+ * The refusal for a write onto a hidden document. It names the document by the name the agent
19227
+ * gave, never by a title or alias it did not, so it says only that a name it holds is taken.
19228
+ */
19229
+ function protectedDocument(asked) {
19230
+ return new ToolError("protected_document", `"${asked}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be changed here - the user can unlock it in EtherPK.`);
19231
+ }
19232
+ /** The document an agent asked to change, with its text, refusing a hidden one as protected. */
19233
+ async function requireWritable(graph, asked) {
19234
+ const identity = requireIdentity(graph, asked);
19235
+ const text = await liveText(graph, identity);
19236
+ if (isHidden(hiddenKeys(graph), identity) || holdsEncryptedText(text)) throw protectedDocument(asked);
19237
+ return {
19238
+ identity,
19239
+ text
19240
+ };
18866
19241
  }
18867
19242
  function page$1(items, offset, limit) {
18868
19243
  return {
@@ -18889,12 +19264,11 @@ async function listDocuments(graph, args = {}) {
18889
19264
  const limit = bounded(args.limit, 200, 200);
18890
19265
  for (const day of [args.from, args.to]) if (day !== void 0 && !isJournalConcept(day)) throw new ToolError("invalid_argument", `"${day}" is not a day: from and to are YYYY-MM-DD.`);
18891
19266
  const kind = args.from !== void 0 || args.to !== void 0 ? "journal" : args.kind;
18892
- const protectedKeys = new Set(graph.index.allConcepts().filter((candidate) => candidate.protected && (candidate.kind === "page" || candidate.kind === "journal")).map((candidate) => candidate.key));
18893
- const all = graph.store.listDocuments().filter((doc) => !kind || doc.kind === kind).filter((doc) => doc.kind !== "journal" || (args.from === void 0 || doc.concept >= args.from) && (args.to === void 0 || doc.concept <= args.to)).map((doc) => ({
19267
+ const hidden = hiddenKeys(graph);
19268
+ const all = graph.store.listDocuments().filter((doc) => !isHidden(hidden, doc)).filter((doc) => !kind || doc.kind === kind).filter((doc) => doc.kind !== "journal" || (args.from === void 0 || doc.concept >= args.from) && (args.to === void 0 || doc.concept <= args.to)).map((doc) => ({
18894
19269
  concept: doc.concept,
18895
19270
  kind: doc.kind,
18896
- aliases: doc.aliases,
18897
- ...protectedKeys.has(doc.key) ? { protected: true } : {}
19271
+ aliases: doc.aliases
18898
19272
  }));
18899
19273
  const paged = page$1(all, offset, limit);
18900
19274
  return {
@@ -18905,9 +19279,7 @@ async function listDocuments(graph, args = {}) {
18905
19279
  }
18906
19280
  async function readDocument(graph, concept) {
18907
19281
  await graph.store.refresh();
18908
- const identity = requireIdentity(graph, concept);
18909
- const text = await liveText(graph, identity);
18910
- refuseIfProtected(identity.concept, text);
19282
+ const { identity, text } = await requireReadable(graph, concept);
18911
19283
  const capped = capText(text, READ_TEXT_CAP);
18912
19284
  return {
18913
19285
  concept: identity.concept,
@@ -18949,8 +19321,9 @@ async function searchSemantic(graph, query, offset, limit) {
18949
19321
  throw new ToolError("semantic_unavailable", error instanceof Error ? error.message : String(error));
18950
19322
  }
18951
19323
  const result = await semantic.search(query, offset, limit);
19324
+ const hidden = hiddenKeys(graph);
18952
19325
  return {
18953
- results: result.groups.map((group) => ({
19326
+ results: result.groups.filter((group) => !hidden.has(conceptKey(group.concept))).map((group) => ({
18954
19327
  concept: group.concept,
18955
19328
  kind: group.kind,
18956
19329
  similarity: round(group.similarity),
@@ -18971,17 +19344,31 @@ async function searchSemantic(graph, query, offset, limit) {
18971
19344
  function round(similarity) {
18972
19345
  return Math.round(similarity * 1e3) / 1e3;
18973
19346
  }
18974
- /** The index's text group, read as Search reads it (shared with the browser's Agent Chat). */
18975
- function searchText(graph, query, offset, limit) {
18976
- return searchText$1(graph.index, query, offset, limit);
19347
+ /**
19348
+ * The index's text group, read as Search reads it (shared with the browser's Agent Chat). The index
19349
+ * holds no protected text, but a document holding a fence beside plain text is flagged and its
19350
+ * plain text indexed, so flagged names are taken out here, as Agent Chat does.
19351
+ */
19352
+ async function searchText(graph, query, offset, limit) {
19353
+ const found = await searchText$1(graph.index, query, offset, limit);
19354
+ const hidden = hiddenKeys(graph);
19355
+ return {
19356
+ ...found,
19357
+ results: found.results.filter((result) => !hidden.has(conceptKey(result.concept)))
19358
+ };
18977
19359
  }
18978
19360
  async function backlinks(graph, concept) {
18979
19361
  const target = concept.trim() === "today" ? todayISO() : concept.trim();
18980
19362
  if (target === "") throw new ToolError("invalid_argument", "concept must not be empty.");
18981
19363
  await graph.store.refresh();
19364
+ const hidden = hiddenKeys(graph);
19365
+ if (hidden.has(conceptKey(target))) return {
19366
+ concept: target,
19367
+ sources: []
19368
+ };
18982
19369
  return {
18983
19370
  concept: target,
18984
- sources: backlinkSources(await graph.index.backlinks(target))
19371
+ sources: backlinkSources(await graph.index.backlinks(target)).filter((source) => !hidden.has(conceptKey(source.concept)))
18985
19372
  };
18986
19373
  }
18987
19374
  /**
@@ -18992,7 +19379,7 @@ async function backlinks(graph, concept) {
18992
19379
  async function graphInsights(graph, args = {}) {
18993
19380
  const limit = Math.max(1, bounded(args.limit, 15, 50));
18994
19381
  await graph.store.refresh();
18995
- const model = createGraphModel(await graph.index.linkGraph());
19382
+ const model = await visibleGraphModel(graph);
18996
19383
  const shown = visibleGraph(model, {
18997
19384
  journals: args.journals ?? true,
18998
19385
  pageless: args.pageless ?? "mentioned-twice"
@@ -19031,10 +19418,21 @@ async function graphInsights(graph, args = {}) {
19031
19418
  }))
19032
19419
  };
19033
19420
  }
19034
- /** The fewest wikilink steps from one concept to another, through every concept, or null when nothing joins them. */
19421
+ /**
19422
+ * The Graph View's model of every concept an agent may see: the index's link graph without the
19423
+ * protected documents, so no Hub, Pageless Concept, Cluster, Bridge or path can name one.
19424
+ */
19425
+ async function visibleGraphModel(graph) {
19426
+ return createGraphModel(linkGraphWithoutProtected(await graph.index.linkGraph(), hiddenKeys(graph)));
19427
+ }
19428
+ /**
19429
+ * The fewest wikilink steps from one concept to another, through every concept an agent may see,
19430
+ * or null when nothing joins them. A protected document is neither an end (`not_found`, as a name
19431
+ * nothing has) nor a step: a route only through one is no route.
19432
+ */
19035
19433
  async function graphPath(graph, args) {
19036
19434
  await graph.store.refresh();
19037
- const model = createGraphModel(await graph.index.linkGraph());
19435
+ const model = await visibleGraphModel(graph);
19038
19436
  const resolve = (asked) => {
19039
19437
  const name = asked.trim() === "today" ? todayISO() : asked.trim();
19040
19438
  if (name === "") throw new ToolError("invalid_argument", "from and to must not be empty.");
@@ -19064,23 +19462,53 @@ async function graphPath(graph, args) {
19064
19462
  steps: path ? path.length - 1 : null
19065
19463
  };
19066
19464
  }
19465
+ /**
19466
+ * The concept and statuses `tasks` lists: a lane reference's, or the arguments'. A lane reference
19467
+ * names the board's concept exactly as the board queries it (no `today` shorthand: a board's
19468
+ * concept is a name), and its one status; a concept or statuses given beside it are refused rather
19469
+ * than one silently winning.
19470
+ */
19471
+ function taskSelection(graph, args) {
19472
+ if (args.reference !== void 0) {
19473
+ const lane = parseLaneReference(args.reference);
19474
+ if (!lane) throw new ToolError("invalid_argument", "reference is not a lane reference. Pass the text Copy lane reference wrote, or its etherpk:/g/…#lane= address; for one task, use read_task.");
19475
+ if (args.concept !== void 0 || args.statuses !== void 0) throw new ToolError("invalid_argument", "A lane reference names the concept and status itself: pass reference without concept or statuses.");
19476
+ if (graph.backend.kind === "synced" && lane.graphId !== graph.graphId) throw new ToolError("other_graph", `That lane reference is for another graph. This server serves "${graph.name}" (${graph.graphId}); ask the user to connect the graph the reference is from.`);
19477
+ return {
19478
+ concept: lane.concept,
19479
+ statuses: [lane.status]
19480
+ };
19481
+ }
19482
+ const statuses = args.statuses ?? OPEN_TASK_STATUSES;
19483
+ for (const status of statuses) if (!TASK_STATUSES.includes(status)) throw new ToolError("invalid_argument", `Unknown task status "${status}".`);
19484
+ return {
19485
+ concept: args.concept?.trim() ? args.concept.trim() === "today" ? todayISO() : args.concept.trim() : null,
19486
+ statuses
19487
+ };
19488
+ }
19067
19489
  async function tasks(graph, args = {}) {
19068
19490
  const offset = bounded(args.offset, 0, Number.MAX_SAFE_INTEGER);
19069
19491
  const limit = bounded(args.limit, 100, 200);
19070
- const statuses = args.statuses ?? OPEN_TASK_STATUSES;
19071
- for (const status of statuses) if (!TASK_STATUSES.includes(status)) throw new ToolError("invalid_argument", `Unknown task status "${status}".`);
19492
+ const { concept, statuses } = taskSelection(graph, args);
19072
19493
  const priorities = args.priorities ? args.priorities.map((priority) => priority === "none" ? null : priority) : [...TASK_PRIORITY_FILTERS];
19073
19494
  await graph.store.refresh();
19495
+ const hidden = hiddenKeys(graph);
19496
+ if (concept !== null && hidden.has(conceptKey(concept))) return {
19497
+ tasks: [],
19498
+ total: 0,
19499
+ hasMore: false
19500
+ };
19074
19501
  const result = await graph.index.tasks({
19075
- concept: args.concept?.trim() ? args.concept.trim() === "today" ? todayISO() : args.concept.trim() : null,
19502
+ concept,
19076
19503
  statuses,
19077
19504
  priorities,
19078
19505
  due: args.due ?? "any",
19079
19506
  groupBy: "document",
19080
19507
  today: todayISO()
19081
19508
  }, offset, limit);
19509
+ const shown = result.hits.filter((hit) => !hidden.has(conceptKey(hit.concept)));
19082
19510
  return {
19083
- tasks: await Promise.all(result.hits.map(async (hit) => ({
19511
+ tasks: await Promise.all(shown.map(async (hit) => ({
19084
19512
  concept: hit.concept,
19085
19513
  kind: hit.kind,
19086
19514
  line: hit.line,
@@ -19117,14 +19545,15 @@ async function withTemplate(graph, template, into, text) {
19117
19545
  }
19118
19546
  /** The body a copy of the Template named `name` takes, or a refusal that says how to find one. */
19119
19547
  async function templateBodyFor(graph, name) {
19120
- const identity = resolveIdentity(graph, name.trim());
19548
+ const found = resolveIdentity(graph, name.trim());
19549
+ const identity = found && await visibleText(graph, found) !== null ? found : null;
19121
19550
  let raw = "";
19122
19551
  if (identity) {
19123
19552
  await graph.store.whenReady(identity.concept);
19124
19553
  raw = graph.store.openRaw(identity.concept).getText();
19125
19554
  }
19126
- const { data, body } = parseFrontmatter(raw);
19127
- if (!identity || !isTemplate(data, identity.kind) || isProtectedDocumentText(body)) throw new ToolError("invalid_argument", `"${name}" is not a Template. A page is a Template when its frontmatter says template: true; search for template:true to list them.`);
19555
+ const { data } = parseFrontmatter(raw);
19556
+ if (!identity || !isTemplate(data, identity.kind)) throw new ToolError("invalid_argument", `"${name}" is not a Template. A page is a Template when its frontmatter says template: true; search for template:true to list them.`);
19128
19557
  return templateBody(raw);
19129
19558
  }
19130
19559
  /**
@@ -19181,9 +19610,7 @@ function changeAsWritten(text, from, to, replacement) {
19181
19610
  async function editDocument(graph, args) {
19182
19611
  if (args.old === "") throw new ToolError("invalid_argument", "old must not be empty.");
19183
19612
  await graph.store.refresh();
19184
- const identity = requireIdentity(graph, args.concept);
19185
- const text = await liveText(graph, identity);
19186
- refuseIfProtected(identity.concept, text);
19613
+ const { identity, text } = await requireWritable(graph, args.concept);
19187
19614
  const first = text.indexOf(args.old);
19188
19615
  if (first === -1) throw new ToolError("no_match", `"${identity.concept}" does not contain the text to replace. Read the document again - it may have changed.`);
19189
19616
  if (text.indexOf(args.old, first + 1) !== -1) throw new ToolError("ambiguous_match", `The text to replace occurs more than once in "${identity.concept}". Include more surrounding text so it matches exactly once.`);
@@ -19212,8 +19639,7 @@ async function appendDocument(graph, args) {
19212
19639
  created: true
19213
19640
  };
19214
19641
  }
19215
- const current = await liveText(graph, existing);
19216
- refuseIfProtected(existing.concept, current);
19642
+ const { text: current } = await requireWritable(graph, target);
19217
19643
  const appended = `${current === "" || current.endsWith("\n") ? "" : "\n"}${text}${text.endsWith("\n") ? "" : "\n"}`;
19218
19644
  graph.store.open(existing.concept).applyChange(changeAsWritten(current, current.length, current.length, appended), "external");
19219
19645
  await settle$2(graph);
@@ -19227,7 +19653,11 @@ async function createPage(graph, args) {
19227
19653
  if (title === "") throw new ToolError("invalid_argument", "title must not be empty.");
19228
19654
  if (isJournalConcept(title)) throw new ToolError("invalid_argument", `"${title}" is a calendar day, so it names a journal entry - use append_document to write to it.`);
19229
19655
  await graph.store.refresh();
19230
- if (resolveIdentity(graph, title)) throw new ToolError("already_exists", `A document already answers to "${title}". Use edit_document or append_document instead.`);
19656
+ const taken = resolveIdentity(graph, title);
19657
+ if (taken) {
19658
+ if (await visibleText(graph, taken) === null) throw protectedDocument(title);
19659
+ throw new ToolError("already_exists", `A document already answers to "${title}". Use edit_document or append_document instead.`);
19660
+ }
19231
19661
  await graph.store.createPage(title, asWritten(await withTemplate(graph, args.template, title, args.text)));
19232
19662
  if (args.frontmatter && Object.keys(args.frontmatter).length > 0) {
19233
19663
  await graph.store.whenReady(title);
@@ -19247,9 +19677,7 @@ async function createPage(graph, args) {
19247
19677
  async function setFrontmatter(graph, args) {
19248
19678
  if (!args.patch || typeof args.patch !== "object" || Array.isArray(args.patch)) throw new ToolError("invalid_argument", "patch must be an object of frontmatter keys.");
19249
19679
  await graph.store.refresh();
19250
- const identity = requireIdentity(graph, args.concept);
19251
- const body = await liveText(graph, identity);
19252
- refuseIfProtected(identity.concept, body);
19680
+ const { identity } = await requireWritable(graph, args.concept);
19253
19681
  const raw = graph.store.openRaw(identity.concept).getText();
19254
19682
  const next = withAliasesInAddedBlock(raw, patchedText(raw, args.patch), identity.aliases);
19255
19683
  applyBlock(graph, identity.concept, raw, next);
@@ -19275,9 +19703,42 @@ function conceptExists(graph, concept) {
19275
19703
  async function referencingDocuments(graph, concept) {
19276
19704
  return (await graph.index.backlinks(concept)).filter((group) => referencedInBody(group, concept)).map((group) => group.sourceConcept);
19277
19705
  }
19278
- /** Protected documents in the graph: their references can be neither seen nor rewritten. */
19279
- function protectedDocumentCount(graph) {
19280
- return graph.index.allConcepts().filter((c) => c.protected && (c.kind === "page" || c.kind === "journal")).length;
19706
+ /** How many documents are hidden from the agent: a count, never their names. */
19707
+ function protectedDocumentCount(graph, keys = hiddenKeys(graph)) {
19708
+ return graph.store.listDocuments().filter((doc) => isHidden(keys, doc)).length;
19709
+ }
19710
+ /**
19711
+ * What a rename may tell an agent. A rename carries a protected page scoped by the old name along,
19712
+ * as a person's rename does, but the plan and the result name each document they touch, so every
19713
+ * hidden document's names - before the rename and after it - are taken out of them. A refusal that
19714
+ * names one (a protected document never merges, ADR 0062) is replaced by one that does not.
19715
+ */
19716
+ function renameDisclosure(graph, plan) {
19717
+ const keys = hiddenKeys(graph);
19718
+ const names = [];
19719
+ for (const doc of graph.store.listDocuments()) if (isHidden(keys, doc)) names.push(doc.concept, ...doc.aliases, landedName(plan, doc.concept));
19720
+ const hiddenNames = new Set(names.map(conceptKey));
19721
+ const hides = (name) => hiddenNames.has(conceptKey(name));
19722
+ return {
19723
+ hides,
19724
+ refusal(refusal) {
19725
+ if (refusal === null) return null;
19726
+ const lower = refusal.toLowerCase();
19727
+ if (!names.some((name) => lower.includes(name.toLowerCase()))) return refusal;
19728
+ return "The rename would merge a protected document, and a protected document never merges. Choose a different name.";
19729
+ }
19730
+ };
19731
+ }
19732
+ /**
19733
+ * The document a rename starts from, if the name is a document's, refusing a hidden one; and a
19734
+ * refusal when the new name is a hidden document's other than that one, which a rename would merge.
19735
+ */
19736
+ async function renameEnds(graph, from, to) {
19737
+ const identity = resolveIdentity(graph, from);
19738
+ if (identity && await visibleText(graph, identity) === null) throw protectedDocument(from);
19739
+ const onto = to === "" ? null : resolveIdentity(graph, to);
19740
+ if (onto && onto.key !== identity?.key && await visibleText(graph, onto) === null) throw protectedDocument(to);
19741
+ return identity;
19281
19742
  }
19282
19743
  function renameStepView(step) {
19283
19744
  return {
@@ -19300,24 +19761,23 @@ async function planRename$1(graph, args) {
19300
19761
  if (from === "") throw new ToolError("invalid_argument", "from must not be empty.");
19301
19762
  await graph.store.refresh();
19302
19763
  if (!conceptExists(graph, from)) throw new ToolError("not_found", `Nothing in the graph is named "${from}".`);
19303
- const identity = resolveIdentity(graph, from);
19304
- if (identity) refuseIfProtected(identity.concept, await liveText(graph, identity));
19305
- const subject = identity?.concept ?? from;
19764
+ const subject = (await renameEnds(graph, from, to))?.concept ?? from;
19306
19765
  const referencing = await referencingDocuments(graph, subject);
19307
19766
  const plan = await graph.store.planRename(subject, to, referencing.length);
19308
19767
  const steps = renameSteps(plan);
19768
+ const { hides, refusal } = renameDisclosure(graph, plan);
19309
19769
  return {
19310
19770
  from: subject,
19311
19771
  to,
19312
- refusal: plan.refusal,
19772
+ refusal: refusal(plan.refusal),
19313
19773
  direct: renameStepView(plan.direct),
19314
- cascade: plan.cascade.map(renameStepView),
19315
- referencingDocuments: referencing,
19316
- merges: steps.filter((step) => step.merges).map((step) => ({
19774
+ cascade: plan.cascade.filter((step) => !hides(step.from)).map(renameStepView),
19775
+ referencingDocuments: referencing.filter((name) => !hides(name)),
19776
+ merges: steps.filter((step) => step.merges && !hides(step.from) && !hides(step.into)).map((step) => ({
19317
19777
  from: step.from,
19318
19778
  into: step.into
19319
19779
  })),
19320
- aliases: plan.aliases.map((alias) => ({
19780
+ aliases: plan.aliases.filter((alias) => !hides(alias.holder)).map((alias) => ({
19321
19781
  document: alias.holder,
19322
19782
  from: alias.from,
19323
19783
  to: alias.to
@@ -19341,12 +19801,11 @@ async function rename$1(graph, args) {
19341
19801
  if (strategy !== "rewrite" && strategy !== "alias") throw new ToolError("invalid_argument", "strategy must be \"rewrite\" or \"alias\".");
19342
19802
  await graph.store.refresh();
19343
19803
  if (!conceptExists(graph, from)) throw new ToolError("not_found", `Nothing in the graph is named "${from}".`);
19344
- const identity = resolveIdentity(graph, from);
19345
- if (identity) refuseIfProtected(identity.concept, await liveText(graph, identity));
19346
- const subject = identity?.concept ?? from;
19804
+ const subject = (await renameEnds(graph, from, to))?.concept ?? from;
19347
19805
  const referencing = await referencingDocuments(graph, subject);
19348
19806
  const plan = await graph.store.planRename(subject, to, referencing.length);
19349
- if (plan.refusal) throw new ToolError("invalid_argument", plan.refusal);
19807
+ const { hides, refusal } = renameDisclosure(graph, plan);
19808
+ if (plan.refusal) throw new ToolError("invalid_argument", refusal(plan.refusal));
19350
19809
  if (mergeCount(plan) > 0 && !args.confirm_merge) throw new ToolError("merge_requires_confirmation", `Renaming "${subject}" to "${to}" would merge ${renameSteps(plan).filter((step) => step.merges).map((step) => `"${step.from}" into "${step.into}"`).join(", ")}: the documents' contents are joined into one and cannot be separated afterwards. Call rename again with confirm_merge: true to do it, or choose a name that is not taken.`);
19351
19810
  let result;
19352
19811
  try {
@@ -19370,13 +19829,13 @@ async function rename$1(graph, args) {
19370
19829
  return {
19371
19830
  concept: result.concept,
19372
19831
  strategy,
19373
- rewrittenDocuments: result.rewrittenDocuments,
19374
- cascaded: plan.cascade.map((step) => ({
19832
+ rewrittenDocuments: result.rewrittenDocuments.filter((name) => !hides(name)),
19833
+ cascaded: plan.cascade.filter((step) => !hides(step.from)).map((step) => ({
19375
19834
  from: step.from,
19376
19835
  to: step.into
19377
19836
  })),
19378
19837
  merged: result.merged,
19379
- aliasesRewritten: result.aliasesRewritten
19838
+ aliasesRewritten: result.aliasesRewritten.filter((name) => !hides(name))
19380
19839
  };
19381
19840
  }
19382
19841
  /**
@@ -19387,13 +19846,13 @@ async function rename$1(graph, args) {
19387
19846
  async function setAliases(graph, args) {
19388
19847
  if (!Array.isArray(args.aliases) || args.aliases.some((alias) => typeof alias !== "string")) throw new ToolError("invalid_argument", "aliases must be a list of names.");
19389
19848
  await graph.store.refresh();
19390
- const identity = requireIdentity(graph, args.concept);
19391
- refuseIfProtected(identity.concept, await liveText(graph, identity));
19849
+ const { identity } = await requireWritable(graph, args.concept);
19392
19850
  const aliases = [];
19393
19851
  for (const raw of args.aliases) {
19394
19852
  const alias = raw.trim();
19395
19853
  if (alias === "" || conceptKey(alias) === identity.key || aliases.some((a) => conceptKey(a) === conceptKey(alias))) continue;
19396
19854
  const holder = resolveIdentity(graph, alias);
19855
+ if (holder && holder.key !== identity.key && await visibleText(graph, holder) === null) throw protectedDocument(alias);
19397
19856
  if (holder && holder.key !== identity.key) throw new ToolError("name_taken", `"${alias}" is already a name of "${holder.concept}", so it cannot be an alias of "${identity.concept}".`);
19398
19857
  aliases.push(alias);
19399
19858
  }
@@ -19410,13 +19869,6 @@ async function setAliases(graph, args) {
19410
19869
  aliases: resolveIdentity(graph, identity.concept)?.aliases ?? aliases
19411
19870
  };
19412
19871
  }
19413
- /** Every asset reference in a body: `../assets/<name>` at any depth, as markdown or HTML writes it. */
19414
- var ASSET_REFS = /(?:\.\.\/)+assets\/[^\s)"'<>\]]+/g;
19415
- function assetReferencesIn(body) {
19416
- const refs = [];
19417
- for (const match of body.matchAll(ASSET_REFS)) refs.push(match[0]);
19418
- return refs;
19419
- }
19420
19872
  function requireAssets(graph) {
19421
19873
  if (!graph.assets) throw new ToolError("assets_unavailable", "This process has no asset storage for the graph, so assets cannot be read or added here.");
19422
19874
  return graph.assets;
@@ -19442,7 +19894,9 @@ function displayNameOf(ref) {
19442
19894
  async function reachable(graph, identity) {
19443
19895
  const assets = requireAssets(graph);
19444
19896
  const usage = await graph.index.assetUsage([identity]);
19445
- if (usage.documents.length > 0) return usage.documents.map((d) => ({
19897
+ const hidden = hiddenKeys(graph);
19898
+ const documents = usage.documents.filter((d) => !hidden.has(conceptKey(d.concept)));
19899
+ if (documents.length > 0) return documents.map((d) => ({
19446
19900
  concept: d.concept,
19447
19901
  kind: d.kind
19448
19902
  }));
@@ -19536,11 +19990,13 @@ async function listAssets(graph, args = {}) {
19536
19990
  let bodies;
19537
19991
  let unconfirmed = [];
19538
19992
  if (args.concept !== void 0 && args.concept.trim() !== "") {
19539
- const identity = requireIdentity(graph, args.concept);
19540
- const text = await liveText(graph, identity);
19541
- refuseIfProtected(identity.concept, text);
19993
+ const { identity, text } = await requireReadable(graph, args.concept);
19542
19994
  bodies = /* @__PURE__ */ new Map([[identity.concept, text]]);
19543
- } else ({bodies, unconfirmed} = await graph.store.readBodies());
19995
+ } else {
19996
+ ({bodies, unconfirmed} = await graph.store.readBodies());
19997
+ const hidden = hiddenKeys(graph);
19998
+ for (const [concept, body] of bodies) if (hidden.has(conceptKey(concept)) || holdsEncryptedText(body)) bodies.delete(concept);
19999
+ }
19544
20000
  const found = /* @__PURE__ */ new Map();
19545
20001
  for (const [concept, body] of bodies) for (const ref of assetReferencesIn(body)) {
19546
20002
  const id = assets.identify(ref);
@@ -19583,23 +20039,16 @@ async function readDocuments(graph, args) {
19583
20039
  if (args.concepts.length > 20) throw new ToolError("too_many", `At most 20 documents per call - ask again for the rest.`);
19584
20040
  await graph.store.refresh();
19585
20041
  let budget = READ_MANY_TEXT_CAP;
20042
+ const hidden = hiddenKeys(graph);
19586
20043
  const documents = [];
19587
20044
  for (const wanted of args.concepts) {
19588
20045
  const identity = resolveIdentity(graph, wanted);
19589
- if (!identity) {
20046
+ const text = identity ? await visibleText(graph, identity, hidden) : null;
20047
+ if (!identity || text === null) {
19590
20048
  documents.push({
19591
20049
  concept: wanted,
19592
20050
  error: "not_found",
19593
- message: `No document is named "${wanted}".`
19594
- });
19595
- continue;
19596
- }
19597
- const text = await liveText(graph, identity);
19598
- if (isProtectedDocumentText(text)) {
19599
- documents.push({
19600
- concept: identity.concept,
19601
- error: "protected_document",
19602
- message: `"${identity.concept}" is a protected document and cannot be read here.`
20051
+ message: notFound(wanted).message
19603
20052
  });
19604
20053
  continue;
19605
20054
  }
@@ -19628,7 +20077,7 @@ async function readDocuments(graph, args) {
19628
20077
  */
19629
20078
  async function setTask(graph, args) {
19630
20079
  if (args.reference !== void 0) {
19631
- const found = await requireReferencedTask(graph, args.reference);
20080
+ const found = await requireReferencedTask(graph, args.reference, "write");
19632
20081
  return setTask(graph, {
19633
20082
  concept: found.document,
19634
20083
  line: found.line,
@@ -19647,9 +20096,7 @@ async function setTask(graph, args) {
19647
20096
  ].includes(changes.priority)) throw new ToolError("invalid_argument", "priority must be 1, 2, 3 or null.");
19648
20097
  for (const [key, value] of [["due", changes.due], ["scheduled", changes.scheduled]]) if (value !== void 0 && value !== null && !isJournalConcept(value)) throw new ToolError("invalid_argument", `${key} must be a day as YYYY-MM-DD, or null.`);
19649
20098
  await graph.store.refresh();
19650
- const identity = requireIdentity(graph, args.concept);
19651
- const text = await liveText(graph, identity);
19652
- refuseIfProtected(identity.concept, text);
20099
+ const { identity, text } = await requireWritable(graph, args.concept);
19653
20100
  const lines = text.split("\n");
19654
20101
  const current = lines[line];
19655
20102
  const parsed = current === void 0 ? null : parseTaskLine(current);
@@ -19689,16 +20136,18 @@ async function setTask(graph, args) {
19689
20136
  }
19690
20137
  /** Where a Task Reference is resolved in this graph: its documents, read live, and its index. */
19691
20138
  function referenceSources(graph) {
20139
+ const hidden = hiddenKeys(graph);
19692
20140
  return {
19693
20141
  graphId: graph.backend.kind === "synced" ? graph.graphId : null,
19694
- resolveDocument: (name) => resolveIdentity(graph, name)?.concept ?? null,
20142
+ resolveDocument: (name) => {
20143
+ const identity = resolveIdentity(graph, name);
20144
+ return identity && !isHidden(hidden, identity) ? identity.concept : null;
20145
+ },
19695
20146
  async readBody(document) {
19696
20147
  const identity = resolveIdentity(graph, document);
19697
- if (!identity) return null;
19698
- const text = await liveText(graph, identity);
19699
- return isProtectedDocumentText(text) ? null : text;
20148
+ return identity ? visibleText(graph, identity, hidden) : null;
19700
20149
  },
19701
- allTasks: () => everyIndexedTask(graph.index, todayISO())
20150
+ allTasks: async () => (await everyIndexedTask(graph.index, todayISO())).filter((task) => !hidden.has(conceptKey(task.document)))
19702
20151
  };
19703
20152
  }
19704
20153
  /** The Task Reference to the task at `line` of `concept`, whose label is `label`. */
@@ -19711,8 +20160,12 @@ async function referenceFor(graph, concept, line, label) {
19711
20160
  fingerprint
19712
20161
  });
19713
20162
  }
19714
- /** The task a Task Reference names in this graph, or the error that says why there is none. */
19715
- async function requireReferencedTask(graph, reference) {
20163
+ /**
20164
+ * The task a Task Reference names in this graph, or the error that says why there is none. A
20165
+ * reference into a hidden document finds nothing; to `write` there it refuses as protected, as a
20166
+ * write by the document's name does, since the reference already names the document.
20167
+ */
20168
+ async function requireReferencedTask(graph, reference, purpose = "read") {
19716
20169
  const parsed = parseTaskReference(reference);
19717
20170
  if (!parsed) throw new ToolError("invalid_argument", "That is not a task reference: one is etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint>, as Copy task reference in EtherPK writes it.");
19718
20171
  await graph.store.refresh();
@@ -19720,6 +20173,8 @@ async function requireReferencedTask(graph, reference) {
19720
20173
  if (found.ok) return found;
19721
20174
  if (found.code === "other_graph") throw new ToolError("other_graph", `That task reference is for another graph. This server serves "${graph.name}" (${found.servedGraphId}); ask the user to connect the graph the reference is from.`);
19722
20175
  if (found.code === "task_ambiguous") throw new ToolError("task_ambiguous", `More than one task has those words (${found.candidates.map((candidate) => `"${candidate.document}" line ${candidate.line}`).join(", ")}), so none was chosen. Ask the user which one, or name it by concept and line.`);
20176
+ const named = resolveIdentity(graph, parsed.document);
20177
+ if (purpose === "write" && named && await visibleText(graph, named) === null) throw protectedDocument(parsed.document);
19723
20178
  throw new ToolError("task_not_found", "No task in the graph has those words now: it was edited or deleted. Ask the user for a fresh reference.");
19724
20179
  }
19725
20180
  /**
@@ -19750,6 +20205,7 @@ async function readTask(graph, args) {
19750
20205
  const { blocks } = deriveDoc(found.body);
19751
20206
  const block = blocks.find((candidate) => candidate.startLine === found.line);
19752
20207
  const end = block ? subtreeEnd(blocks, block.localId) : found.line;
20208
+ const structure = readTaskStructure(lines, found.line);
19753
20209
  return {
19754
20210
  concept: found.document,
19755
20211
  line: found.line,
@@ -19763,43 +20219,41 @@ async function readTask(graph, args) {
19763
20219
  detail: lines.slice(found.line + 1, end + 1).join("\n"),
19764
20220
  foundBy: found.foundBy,
19765
20221
  reference: await referenceFor(graph, found.document, found.line, bulletLabel(line)),
19766
- assets: [...new Set(assetReferencesIn(lines.slice(found.line, end + 1).join("\n")))]
20222
+ assets: structure?.assets ?? [...new Set(assetReferencesIn(lines.slice(found.line, end + 1).join("\n")))],
20223
+ comments: structure ? taskComments(lines, structure) : []
19767
20224
  };
19768
20225
  }
19769
20226
  /**
19770
- * Add a note under the task a Task Reference names: the text as a bullet one level under the
19771
- * task, after its existing detail, so a Kanban Board's Task Detail shows it with the task. Text
19772
- * that is already bullets is nested as it is.
20227
+ * Add a note to the task a Task Reference names as a [[Task Comment]] (ADR 0170): a bullet under the
20228
+ * task's `Comments` bullet, after the comments already there, the Comments bullet started as the
20229
+ * task's last child when it has none. A line of prose becomes one bullet whose later lines continue
20230
+ * it; text that is already bullets is nested as it is. A note written under the task before Comments
20231
+ * existed stays where it is, in the task's description. The Task Editor shows the comment with the
20232
+ * task's others.
19773
20233
  */
19774
20234
  async function addTaskNote(graph, args) {
19775
20235
  if (typeof args.text !== "string" || args.text.trim() === "") throw new ToolError("invalid_argument", "text must not be empty.");
19776
- const found = await requireReferencedTask(graph, args.reference);
19777
- const lines = found.body.split("\n");
19778
- const { blocks } = deriveDoc(found.body);
19779
- const block = blocks.find((candidate) => candidate.startLine === found.line);
19780
- const end = block ? subtreeEnd(blocks, block.localId) : found.line;
19781
- const childIndent = `${/^\s*/.exec(lines[found.line])[0]} `;
19782
- const written = asWritten(args.text.trim());
19783
- const insert = (written.startsWith("- ") ? written : `- ${written.replace(/\n/g, "\n ")}`).split("\n").map((noteLine) => noteLine === "" ? noteLine : childIndent + noteLine).join("\n");
19784
- const at = lines.slice(0, end + 1).reduce((n, l) => n + l.length + 1, 0) - 1;
20236
+ const found = await requireReferencedTask(graph, args.reference, "write");
20237
+ const change = commentChange(found.body, found.line, asCommentBullet(asWritten(args.text.trim())));
20238
+ if (!change) throw new ToolError("task_not_found", "The task moved while the note was being written. Ask the user for a fresh reference.");
19785
20239
  graph.store.open(found.document).applyChange({
19786
- from: at,
19787
- to: at,
19788
- insert: `\n${insert}`
20240
+ from: change.from,
20241
+ to: change.to,
20242
+ insert: change.insert
19789
20243
  }, "external");
19790
20244
  await settle$2(graph);
19791
20245
  return {
19792
20246
  concept: found.document,
19793
20247
  line: found.line,
19794
- noteLine: end + 1,
19795
- reference: await referenceFor(graph, found.document, found.line, bulletLabel(lines[found.line]))
20248
+ noteLine: change.line,
20249
+ reference: await referenceFor(graph, found.document, found.line, bulletLabel(found.body.split("\n")[found.line]))
19796
20250
  };
19797
20251
  }
19798
20252
  /** What an agent should know before it starts: where it is, what is here, what is set up. */
19799
20253
  async function graphInfo(graph) {
19800
20254
  await graph.store.refresh();
19801
20255
  const documents = graph.store.listDocuments();
19802
- const protectedKeys = new Set(graph.index.allConcepts().filter((c) => c.protected && (c.kind === "page" || c.kind === "journal")).map((c) => c.key));
20256
+ const hidden = hiddenKeys(graph);
19803
20257
  const semantic = await graph.semanticOpened();
19804
20258
  const status = semantic ? await semantic.status() : void 0;
19805
20259
  return {
@@ -19808,7 +20262,7 @@ async function graphInfo(graph) {
19808
20262
  documents: {
19809
20263
  pages: documents.filter((d) => d.kind === "page").length,
19810
20264
  journals: documents.filter((d) => d.kind === "journal").length,
19811
- protected: documents.filter((d) => protectedKeys.has(d.key)).length
20265
+ protected: protectedDocumentCount(graph, hidden)
19812
20266
  },
19813
20267
  semantic: status ? {
19814
20268
  state: "open",
@@ -20842,15 +21296,16 @@ function createMcpServer(source, info) {
20842
21296
  `You are connected to the EtherPK knowledge graph "${info.graphName}": daily journal entries and titled pages in plain markdown, linked with [[wikilinks]].`,
20843
21297
  ...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this computer, so reach it only through these tools."] : [],
20844
21298
  `This process holds the EtherPK sign-in and Encryption Keys it needs. Never read, print, copy or search ${info.credentialsDir ?? "~/.config/etherpk"}, or any keychain entry named etherpk-mcp: they are credentials that open the whole account, not notes.`,
20845
- "Concept names are case-insensitive. A protected document is listed with protected: true and cannot be read or written here - tell the user to unlock it in EtherPK if a task needs it.",
21299
+ "Concept names are case-insensitive. Protected documents are not shown here: no list, search, backlink, task or graph answer names one, and a read of one answers not_found. graph_info says how many there are. A write onto a protected document's name is refused with protected_document - tell the user to make that change in EtherPK.",
20846
21300
  "Bullets are \"- \" with two-space nesting. Tasks are \"- [ ]\" / \"- [x]\" with task tags (#P1 #P2 #P3, #W #D #C, #D-YYYY-MM-DD due, #S-YYYY-MM-DD scheduled) right after the checkbox. A free tag such as #bug or #needs-review (letters, digits and single hyphens) is the user's own label and can go anywhere in a task's text; write task tags first.",
20847
21301
  "read_document returns a document's body as text and its frontmatter block as data (the \"frontmatter\" object) - the block is never in the text, so line numbers from search, backlinks and tasks match the text. Set frontmatter keys with set_frontmatter (public, publications, date, author, description and any other key) - a document's title and aliases and a publication page's definition are not frontmatter here and have tools of their own.",
20848
21302
  "Edit with edit_document (an exact, unique old→new replacement) or append_document - read first, then edit, and never paste a whole page back.",
20849
- "To rename a page or concept use plan_rename then rename, never a frontmatter edit: rename carries scoped concepts (\"[[Old]] Notes\") along and by default rewrites every [[Old]] link in the graph to the new name (strategy \"rewrite\") - strategy \"alias\" keeps the old name resolving instead. A rename onto a name that is taken merges two documents and needs confirm_merge: true. References inside protected documents cannot be seen or rewritten.",
21303
+ "To rename a page or concept use plan_rename then rename, never a frontmatter edit: rename carries scoped concepts (\"[[Old]] Notes\") along and by default rewrites every [[Old]] link in the graph to the new name (strategy \"rewrite\") - strategy \"alias\" keeps the old name resolving instead. A rename onto a name that is taken merges two documents and needs confirm_merge: true. References inside protected documents cannot be seen or rewritten, and a protected page under the old name moves with it without being named.",
20850
21304
  "search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this computer - if it is not set up, search says so and names the command.",
20851
21305
  "graph_insights says what the links show across the whole graph (the most-linked concepts, pages many documents ask for that do not exist yet, pages linked to nothing, groups of related concepts and the concepts bridging them), and graph_path finds how two concepts are connected. Use them to answer questions about the shape of the graph, or to suggest pages to write or link.",
20852
21306
  "Start with graph_info to see what you are connected to. read_documents reads several documents in one call. tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
20853
- "A task reference is how a person hands you one task: a few lines naming the graph, the task's words and a reference, etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint> (an earlier version wrote a web address ending in the same #task=). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did under it. Leave its status as it is unless the user asks you to change it. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited it answers task_not_found, and you should ask the user for a fresh one.",
21307
+ "A task reference is how a person hands you one task: a few lines naming the graph, the task's words and a reference, etherpk:/g/<graph>/d/<document>#task=<line>-<fingerprint> (an earlier version wrote a web address ending in the same #task=). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did as a task comment (a bullet under the \"- Comments\" bullet nested directly under the task). Leave its status as it is unless the user asks you to change it. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited it answers task_not_found, and you should ask the user for a fresh one.",
21308
+ "A lane reference is how a person hands you a whole lane of a Kanban board, to work through every task in it or to triage them: a few lines naming the graph, the board and the lane, and a reference, etherpk:/g/<graph>/k/<concept>#lane=<status> (etherpk:/g/<graph>/kanban#lane=<status> for the Graph Kanban, which holds every task in the graph). It is not a web address either. Pass the whole text to tasks as reference to list the lane's tasks as the board shows them now; each comes with its own task reference for read_task, set_task and add_task_note.",
20854
21309
  "Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. publish with dryRun: true renders and reports without writing and needs no folder: run it after editing a publication's pages and fix what it names. Diagrams need a browser the user installs once with \"diagrams setup\".",
20855
21310
  "Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
20856
21311
  "Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document. read_asset writes an asset to a local file you can open, and list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path - name a folder relative to it, never elsewhere.",
@@ -20858,7 +21313,7 @@ function createMcpServer(source, info) {
20858
21313
  ].join("\n") });
20859
21314
  server.registerTool("list_documents", {
20860
21315
  title: "List documents",
20861
- description: `Every page and journal entry in the graph with its aliases - protected documents carry protected: true and have no readable body. from / to narrow to the journal entries of a range of days. Paged, at most 200 per call.`,
21316
+ description: `Every page and journal entry in the graph with its aliases, protected documents left out. from / to narrow to the journal entries of a range of days. Paged, at most 200 per call.`,
20862
21317
  inputSchema: {
20863
21318
  kind: z.enum(["page", "journal"]).optional().describe("Only pages, or only journal entries."),
20864
21319
  from: z.string().optional().describe("Journal entries on or after this day (YYYY-MM-DD) - implies kind journal."),
@@ -20869,12 +21324,12 @@ function createMcpServer(source, info) {
20869
21324
  }, async (args) => run((graph) => listDocuments(graph, args)));
20870
21325
  server.registerTool("read_document", {
20871
21326
  title: "Read a document",
20872
- description: "One document: its body as \"text\" (the markdown after any frontmatter block) and its frontmatter as the \"frontmatter\" object, minus title and aliases (its identity) and any publication definition. Refuses a protected document with error \"protected_document\". Long documents are cut and marked truncated: true.",
21327
+ description: "One document: its body as \"text\" (the markdown after any frontmatter block) and its frontmatter as the \"frontmatter\" object, minus title and aliases (its identity) and any publication definition. A protected document answers not_found, as a name nothing has. Long documents are cut and marked truncated: true.",
20873
21328
  inputSchema: { concept }
20874
21329
  }, async (args) => run((graph) => readDocument(graph, args.concept)));
20875
21330
  server.registerTool("read_documents", {
20876
21331
  title: "Read several documents",
20877
- description: `Up to 20 documents in one call, each as read_document returns it. A protected or unknown document is reported in its place with an error code rather than failing the call. Long texts are cut and marked truncated.`,
21332
+ description: `Up to 20 documents in one call, each as read_document returns it. A protected or unknown document is reported in its place as not_found rather than failing the call. Long texts are cut and marked truncated.`,
20878
21333
  inputSchema: { concepts: z.array(concept).min(1).max(20) }
20879
21334
  }, async (args) => run((graph) => readDocuments(graph, args)));
20880
21335
  server.registerTool("search", {
@@ -20893,13 +21348,13 @@ function createMcpServer(source, info) {
20893
21348
  }, async (args) => run((graph) => search(graph, args)));
20894
21349
  server.registerTool("backlinks", {
20895
21350
  title: "Backlinks",
20896
- description: "Every document that links to a concept with [[Concept]], with the linking block or paragraph, and every document scoped by it (a title such as \"[[Concept]] Notes\" is a reference of kind \"title\"). Aliases are pooled: linking an alias counts.",
21351
+ description: "Every document that links to a concept with [[Concept]], with the linking block or paragraph, and every document scoped by it (a title such as \"[[Concept]] Notes\" is a reference of kind \"title\"). Aliases are pooled: linking an alias counts. Protected documents are never sources, and a protected document's name answers no sources.",
20897
21352
  inputSchema: { concept }
20898
21353
  }, async (args) => run((graph) => backlinks(graph, args.concept)));
20899
21354
  const journals = z.boolean().optional().describe("Count journal entries as part of the graph (default true).");
20900
21355
  server.registerTool("graph_insights", {
20901
21356
  title: "Graph insights",
20902
- description: `What the whole graph's links show, as the Graph View lists it. hubs: the concepts linked from the most documents. pageless: concepts many documents mention that have no page yet (pages worth writing). isolated: pages with no wikilinks in or out (pages to connect). clusters: groups of concepts that link to one another more than to the rest, named after their biggest hub, with their best-known members. bridges: concepts carrying the links between two clusters, with the two they join. shown counts the concepts and lines the clusters and bridges were found in. Hubs, pageless and isolated always count every document. At most 50 rows per list (default 15).`,
21357
+ description: `What the whole graph's links show, as the Graph View lists it. hubs: the concepts linked from the most documents. pageless: concepts many documents mention that have no page yet (pages worth writing). isolated: pages with no wikilinks in or out (pages to connect). clusters: groups of concepts that link to one another more than to the rest, named after their biggest hub, with their best-known members. bridges: concepts carrying the links between two clusters, with the two they join. Protected documents are left out of every list and of the picture, with the links in and out of them. shown counts the concepts and lines the clusters and bridges were found in. Hubs, pageless and isolated always count every document. At most 50 rows per list (default 15).`,
20903
21358
  inputSchema: {
20904
21359
  limit: z.number().int().positive().max(50).optional(),
20905
21360
  journals,
@@ -20912,7 +21367,7 @@ function createMcpServer(source, info) {
20912
21367
  }, async (args) => run((graph) => graphInsights(graph, args)));
20913
21368
  server.registerTool("graph_path", {
20914
21369
  title: "Graph path",
20915
- description: "The fewest wikilink steps between two concepts, in either direction, as the list of concepts passed through; path is null when nothing joins them. Answers \"how is this connected to that?\".",
21370
+ description: "The fewest wikilink steps between two concepts, in either direction, as the list of concepts passed through; path is null when nothing joins them. Answers \"how is this connected to that?\". A path never passes through a protected document, and one as an end answers not_found.",
20916
21371
  inputSchema: {
20917
21372
  from: concept,
20918
21373
  to: concept,
@@ -20921,8 +21376,9 @@ function createMcpServer(source, info) {
20921
21376
  }, async (args) => run((graph) => graphPath(graph, args)));
20922
21377
  server.registerTool("tasks", {
20923
21378
  title: "Tasks",
20924
- description: `Tasks ("- [ ]" bullets) across the graph with their tags, and freeTags: the person's own #words anywhere in a task's text (#bug), which carry no status. Defaults to every unfinished task. A concept filter matches tasks written on that page or on a page named for it ("[[Concept]] Notes"), linking it, or nested under a block or heading that links it. At most 200 per call.`,
21379
+ description: `Tasks ("- [ ]" bullets) across the graph with their tags, and freeTags: the person's own #words anywhere in a task's text (#bug), which carry no status. Defaults to every unfinished task. A concept filter matches tasks written on that page or on a page named for it ("[[Concept]] Notes"), linking it, or nested under a block or heading that links it. A lane reference (a Kanban lane the user copied) in reference lists that lane's tasks: it sets the concept and status, so pass it without concept or statuses; errors invalid_argument (not a lane reference) and other_graph (the lane is in another graph). At most 200 per call.`,
20925
21380
  inputSchema: {
21381
+ reference: z.string().min(1).optional().describe("A lane reference as the user gave it: the whole text, or the etherpk: reference alone. In place of concept and statuses."),
20926
21382
  concept: concept.optional(),
20927
21383
  statuses: z.array(z.enum([
20928
21384
  "open",
@@ -20951,12 +21407,12 @@ function createMcpServer(source, info) {
20951
21407
  }, async (args) => run((graph) => tasks(graph, args)));
20952
21408
  server.registerTool("read_task", {
20953
21409
  title: "Read a task",
20954
- description: "The task a task reference names: its text, status, priority, due and scheduled days, its free tags, its document and current 0-based line, its breadcrumb (the headings and bullets above it), its detail (its continuation lines and everything nested under it), foundBy (at_line, moved or other_document), its current reference, and assets: the images and files the task and its detail show, to read with read_asset. Errors: task_not_found (its words were edited or it was deleted), task_ambiguous (two tasks have its words; the message names them), other_graph (the reference is from another graph).",
21410
+ description: "The task a task reference names: its text, status, priority, due and scheduled days, its free tags, its document and current 0-based line, its breadcrumb (the headings and bullets above it), its detail (its continuation lines and everything nested under it), foundBy (at_line, moved or other_document), its current reference, assets: the images and files the task and its detail show, to read with read_asset, and comments: the task comments, each the text of one bullet under the \"Comments\" bullet nested directly under the task (they are in its detail too). Errors: task_not_found (its words were edited or it was deleted), task_ambiguous (two tasks have its words; the message names them), other_graph (the reference is from another graph).",
20955
21411
  inputSchema: { reference: z.string().min(1).describe("The task reference as the user gave it: the whole text, or the etherpk: reference alone.") }
20956
21412
  }, async (args) => run((graph) => readTask(graph, args)));
20957
21413
  server.registerTool("add_task_note", {
20958
- title: "Add a note under a task",
20959
- description: "Add text under the task a task reference names, one level in, after what is already nested there: a line of text becomes a bullet, and bullets are nested as written. Use it to record what you did about the task. Refuses as read_task does when the reference finds no single task.",
21414
+ title: "Add a comment to a task",
21415
+ description: "Add a task comment to the task a task reference names: a bullet under the task's \"Comments\" bullet, after the comments already there. A \"- Comments\" bullet is started as the task's last child when it has none. A line of text becomes one bullet, and bullets are nested as written. Use it to record what you did about the task. To write a comment by hand instead, add a bullet under \"- Comments\" nested directly under the task. Refuses as read_task does when the reference finds no single task.",
20960
21416
  inputSchema: {
20961
21417
  reference: z.string().min(1).describe("The task reference as the user gave it."),
20962
21418
  text: z.string().min(1).describe("Markdown: a line, or \"- \" bullets.")
@@ -21011,7 +21467,7 @@ function createMcpServer(source, info) {
21011
21467
  }, async (args) => run((graph) => appendDocument(graph, args)));
21012
21468
  server.registerTool("create_page", {
21013
21469
  title: "Create a page",
21014
- description: "Create a new page with the given title, optional markdown body and optional frontmatter (the same keys and rules as set_frontmatter). With template, the page starts with that Template's body, its variables ({{date}}, {{title}}, ...) filled in for the new page, then the text. Refuses a title that already names a page or an alias, or that is a calendar day (use append_document for journal entries).",
21470
+ description: "Create a new page with the given title, optional markdown body and optional frontmatter (the same keys and rules as set_frontmatter). With template, the page starts with that Template's body, its variables ({{date}}, {{title}}, ...) filled in for the new page, then the text. Refuses a title that already names a page or an alias (protected_document when that page is protected), or that is a calendar day (use append_document for journal entries).",
21015
21471
  inputSchema: {
21016
21472
  title: z.string().min(1),
21017
21473
  text: z.string().optional(),
@@ -21021,7 +21477,7 @@ function createMcpServer(source, info) {
21021
21477
  }, async (args) => run((graph) => createPage(graph, args)));
21022
21478
  server.registerTool("plan_rename", {
21023
21479
  title: "Plan a rename",
21024
- description: "What renaming a page or concept would do, before anything changes: the scoped concepts carried along (cascade), the documents whose links would be rewritten (referencingDocuments, by name - read or backlinks any of them), any merge (the new name is already a document's name or alias, so the two would be joined), the aliases that name it as a scope and would be rewritten with it (aliases: the document, the alias and its new form), a refusal if the rename is not allowed, and how many protected documents exist whose references cannot be seen. Journal entries cannot be renamed.",
21480
+ description: "What renaming a page or concept would do, before anything changes: the scoped concepts carried along (cascade), the documents whose links would be rewritten (referencingDocuments, by name - read or backlinks any of them), any merge (the new name is already a document's name or alias, so the two would be joined), the aliases that name it as a scope and would be rewritten with it (aliases: the document, the alias and its new form), a refusal if the rename is not allowed, and how many protected documents exist whose references cannot be seen (protectedDocuments, a count). Protected documents are never named in the plan. A protected page as either name is refused with protected_document. Journal entries cannot be renamed.",
21025
21481
  inputSchema: {
21026
21482
  from: z.string().min(1).describe("The current name: a page title or a concept that only links name."),
21027
21483
  to: z.string().min(1).describe("The new name.")
@@ -21201,7 +21657,7 @@ function createMcpServer(source, info) {
21201
21657
  }, async (args) => run((graph) => previewTheme(graph, args, host)));
21202
21658
  server.registerTool("graph_info", {
21203
21659
  title: "Graph info",
21204
- description: "What you are connected to: the graph's name, whether it is a synced graph (and on which server) or a folder, how many pages and journal entries it has and how many are protected, the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
21660
+ description: "What you are connected to: the graph's name, whether it is a synced graph (and on which server) or a folder, how many pages and journal entries it has and how many of them are protected (protected documents are counted here and shown nowhere else), the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
21205
21661
  inputSchema: {}
21206
21662
  }, async () => run(async (graph) => ({
21207
21663
  ...await graphInfo(graph),