From fb78a844af7a4c810fab8bb3d4152f02e153018d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 4 Jul 2026 00:39:09 +0800
Subject: [PATCH] docs(tools): fix cross-module JSDoc links and the catalog
 source list

Codex review of the vocabulary relocation found two doc-accuracy issues:

- presentation.ts's JSDoc used {@link ToolDefinition...}, which the
  TypeScript language service cannot resolve because presentation.ts
  deliberately does not import index.ts (that would create the cycle the
  split avoids). Demote those three to plain `ToolDefinition` code text;
  same-file and imported @links (TerminalResultView, ContentBlock) stay.
- docs/core-data-structures/tools.md's source header listed only index.ts
  and schema.ts; add presentation.ts, which now owns the presentation
  vocabulary the page documents.
---
 docs/core-data-structures/tools.md      | 2 +-
 packages/core/tools/src/presentation.ts | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index f534ea1cdb..3b1f8d76c2 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -2,7 +2,7 @@
 
 The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine and `ToolSchema` as the model-facing wire shape. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the waterfall execution shapes, and the UI-presentation vocabulary.
 
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
+Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
 ## `ToolDefinition` — a registered tool
 
diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts
index a64fe71eec..b99fa08ebd 100644
--- a/packages/core/tools/src/presentation.ts
+++ b/packages/core/tools/src/presentation.ts
@@ -1,6 +1,6 @@
 /**
  * Tool render-intent vocabulary: the provider-neutral types a tool declares via
- * {@link ToolDefinition.presentCall}/{@link ToolDefinition.presentResult} to say
+ * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say
  * how ONE of its calls renders in a UI (an editor's tool-call card, a CLI log
  * line). A UI bridge switches on the `card` tag to map each intent to its own
  * wire shape, so a UI never special-cases tool names.
@@ -62,7 +62,7 @@ export interface FileDiff {
  * switches on `card` to map it to the bridge's own wire shape. Provider-neutral —
  * the tool owns its presentation, so a UI never special-cases tool names.
  *
- * Returned by {@link ToolDefinition.presentCall}. See the render-intent-union
+ * Returned by `ToolDefinition.presentCall`. See the render-intent-union
  * RFC (docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
  */
 export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView
@@ -144,7 +144,7 @@ export interface DiffCallView {
  * returns. A `card`-tagged union mirroring {@link ToolCallView}: a UI switches on
  * `card`. Lets the tool reformat its result for a UI distinctly from the
  * model-facing text it returned from `execute`. Returned by
- * {@link ToolDefinition.presentResult}; omitting the method keeps the pending
+ * `ToolDefinition.presentResult`; omitting the method keeps the pending
  * title and renders the raw result content.
  */
 export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView