@wienerberliner/pi-markdown-reader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# pi-markdown-reader
+
+Pi extension tools for deterministic, structure-aware Markdown reading.
+
+Instead of sampling long Markdown files with brittle line ranges, agents can inspect a compact outline first, then read complete sections by exact `pathSlug`.
+
+## Install
+
+```bash
+pi install npm:@wienerberliner/pi-markdown-reader
+```
+
+Then restart Pi or run `/reload`.
+
+## Tools
+
+### `markdown_outline`
+
+Returns a flat, source-ordered table of contents for a Markdown file:
+
+- heading level and title
+- hierarchical `pathSlug`
+- `startLine`, `endLine`, and `lineCount`
+- optional frontmatter metadata (`pathSlug`, keys, line span)
+
+Example:
+
+```json
+{
+  "path": "report.md",
+  "includeFrontmatter": true
+}
+```
+
+### `markdown_read`
+
+Reads one or more complete Markdown sections by exact `pathSlug`.
+
+The LLM-facing result is plain Markdown text. Metadata stays in tool details.
+
+Example:
+
+```json
+{
+  "path": "report.md",
+  "sections": [
+    { "pathSlug": "abstract" },
+    { "pathSlug": "results/evidence" }
+  ]
+}
+```
+
+If a document has YAML frontmatter, it can be read with:
+
+```json
+{ "pathSlug": "frontmatter" }
+```
+
+### `markdown_index`
+
+Indexes a directory of Markdown files without reading full bodies. Useful for folders of reports, notes, and generated artifacts.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+For local Pi development in this repository, trust the project and reload Pi. The project `.pi/settings.json` shadows the published npm package and loads the local checkout.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@wienerberliner/pi-markdown-reader",
+  "version": "0.1.0",
+  "description": "Pi extension tools for deterministic, structure-aware Markdown outline and section reading.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Daniel",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "markdown",
+    "markdown-reader"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dasomji/pi-markdown-reader.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dasomji/pi-markdown-reader/issues"
+  },
+  "homepage": "https://github.com/dasomji/pi-markdown-reader#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typebox": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import { createMarkdownIndexTool } from "./tools/markdown-index.js";
+import { createMarkdownOutlineTool } from "./tools/markdown-outline.js";
+import { createMarkdownReadTool } from "./tools/markdown-read.js";
+
+interface ExtensionAPI {
+  registerTool(tool: unknown): void;
+}
+
+export default function markdownReaderExtension(pi: ExtensionAPI) {
+  pi.registerTool(createMarkdownOutlineTool());
+  pi.registerTool(createMarkdownReadTool());
+  pi.registerTool(createMarkdownIndexTool());
+}

package/src/markdown/frontmatter.ts

@@ -0,0 +1,25 @@
+import type { FrontmatterSummary } from "./types.js";
+
+export function findFrontmatter(lines: string[]): FrontmatterSummary | undefined {
+  if (lines.length === 0 || !/^---\s*$/.test(lines[0] ?? "")) return undefined;
+
+  for (let index = 1; index < lines.length; index += 1) {
+    if (/^(---|\.\.\.)\s*$/.test(lines[index] ?? "")) {
+      const rawLines = lines.slice(1, index);
+      const keys = rawLines
+        .map((line) => line.match(/^([A-Za-z0-9_.-]+)\s*:/)?.[1])
+        .filter((key): key is string => Boolean(key));
+      const endLine = index + 1;
+
+      return {
+        pathSlug: "frontmatter",
+        keys: [...new Set(keys)],
+        startLine: 1,
+        endLine,
+        lineCount: endLine,
+      };
+    }
+  }
+
+  return undefined;
+}

package/src/markdown/parse.ts

@@ -0,0 +1,131 @@
+import { findFrontmatter } from "./frontmatter.js";
+import { slugSegment } from "./path-slugs.js";
+import type { Heading, ParsedMarkdown } from "./types.js";
+
+interface RawHeading {
+  level: number;
+  title: string;
+  startLine: number;
+  pathSlug: string;
+}
+
+interface ParseOptions {
+  maxDepth?: number;
+  includeFrontmatter?: boolean;
+}
+
+export function splitMarkdownLines(text: string): string[] {
+  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (normalized.length === 0) return [];
+  const withoutFinalNewline = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+  return withoutFinalNewline.split("\n");
+}
+
+export function parseMarkdown(text: string, options: ParseOptions = {}): ParsedMarkdown {
+  const maxDepth = options.maxDepth ?? 6;
+  const includeFrontmatter = options.includeFrontmatter ?? true;
+  const lines = splitMarkdownLines(text);
+  const frontmatter = findFrontmatter(lines);
+  const rawHeadings = scanHeadings(lines, frontmatter?.endLine ?? 0, Boolean(frontmatter));
+  const headings = computeHeadingSpans(rawHeadings, lines.length).filter((heading) => heading.level <= maxDepth);
+  const firstH1 = rawHeadings.find((heading) => heading.level === 1);
+
+  return {
+    title: firstH1?.title,
+    frontmatter: includeFrontmatter ? frontmatter : undefined,
+    frontmatterKeys: frontmatter?.keys,
+    totalLines: lines.length,
+    lines,
+    headings,
+  };
+}
+
+function scanHeadings(lines: string[], frontmatterEndLine: number, hasFrontmatter: boolean): RawHeading[] {
+  const headings: Omit<RawHeading, "pathSlug">[] = [];
+  let fenceMarker: "`" | "~" | undefined;
+  let fenceLength = 0;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNumber = index + 1;
+    const line = lines[index] ?? "";
+
+    if (lineNumber <= frontmatterEndLine) continue;
+
+    const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const markerRun = fenceMatch[1] ?? "";
+      const marker = markerRun[0] as "`" | "~";
+      if (!fenceMarker) {
+        fenceMarker = marker;
+        fenceLength = markerRun.length;
+      } else if (marker === fenceMarker && markerRun.length >= fenceLength) {
+        fenceMarker = undefined;
+        fenceLength = 0;
+      }
+      continue;
+    }
+
+    if (fenceMarker) continue;
+
+    const headingMatch = line.match(/^ {0,3}(#{1,6})[ \t]+(.+?)\s*$/);
+    if (!headingMatch) continue;
+
+    const level = (headingMatch[1] ?? "").length;
+    const title = (headingMatch[2] ?? "").replace(/[ \t]+#+[ \t]*$/, "").trim();
+    if (!title) continue;
+
+    headings.push({ level, title, startLine: lineNumber });
+  }
+
+  return assignPathSlugs(headings, hasFrontmatter);
+}
+
+function assignPathSlugs(headings: Omit<RawHeading, "pathSlug">[], hasFrontmatter: boolean): RawHeading[] {
+  const stack: RawHeading[] = [];
+  const siblingCounts = new Map<string, number>();
+  if (hasFrontmatter) siblingCounts.set("\u0000frontmatter", 1);
+  const result: RawHeading[] = [];
+
+  for (const heading of headings) {
+    while (stack.length > 0 && stack[stack.length - 1]!.level >= heading.level) {
+      stack.pop();
+    }
+
+    const parentPathSlug = stack[stack.length - 1]?.pathSlug;
+    const baseSegment = slugSegment(heading.title);
+    const counterKey = `${parentPathSlug ?? ""}\u0000${baseSegment}`;
+    const previousCount = siblingCounts.get(counterKey) ?? 0;
+    siblingCounts.set(counterKey, previousCount + 1);
+
+    const segment = previousCount === 0 ? baseSegment : `${baseSegment}-${previousCount}`;
+    const rawHeading = {
+      ...heading,
+      pathSlug: parentPathSlug ? `${parentPathSlug}/${segment}` : segment,
+    };
+
+    result.push(rawHeading);
+    stack.push(rawHeading);
+  }
+
+  return result;
+}
+
+function computeHeadingSpans(rawHeadings: RawHeading[], totalLines: number): Heading[] {
+  return rawHeadings.map((heading, index) => {
+    let endLine = totalLines;
+
+    for (let nextIndex = index + 1; nextIndex < rawHeadings.length; nextIndex += 1) {
+      const nextHeading = rawHeadings[nextIndex]!;
+      if (nextHeading.level <= heading.level) {
+        endLine = nextHeading.startLine - 1;
+        break;
+      }
+    }
+
+    return {
+      ...heading,
+      endLine,
+      lineCount: Math.max(0, endLine - heading.startLine + 1),
+    };
+  });
+}

package/src/markdown/path-slugs.ts

@@ -0,0 +1,13 @@
+export function slugSegment(title: string): string {
+  const normalized = title
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .trim()
+    .replace(/[^\p{Letter}\p{Number}\s_-]+/gu, "")
+    .replace(/[\s_]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  return normalized || "section";
+}

package/src/markdown/sections.ts

@@ -0,0 +1,94 @@
+import type { Heading, ParsedMarkdown, SectionRead } from "./types.js";
+
+export const DEFAULT_MAX_SECTION_LINES = 2_000;
+export const DEFAULT_MAX_SECTION_BYTES = 50 * 1024;
+
+const encoder = new TextEncoder();
+
+export function readSectionByPathSlug(parsed: ParsedMarkdown, pathSlug: string): SectionRead {
+  if (parsed.frontmatter?.pathSlug === pathSlug) {
+    return readSection(parsed, {
+      level: 0,
+      title: "Frontmatter",
+      pathSlug: parsed.frontmatter.pathSlug,
+      startLine: parsed.frontmatter.startLine,
+      endLine: parsed.frontmatter.endLine,
+      lineCount: parsed.frontmatter.lineCount,
+    });
+  }
+
+  const heading = parsed.headings.find((candidate) => candidate.pathSlug === pathSlug);
+  if (!heading) {
+    const available = [parsed.frontmatter?.pathSlug, ...parsed.headings.map((candidate) => candidate.pathSlug)]
+      .filter(Boolean)
+      .join(", ");
+    throw new Error(`No Markdown heading found for pathSlug "${pathSlug}".${available ? ` Available pathSlugs: ${available}` : ""}`);
+  }
+
+  return readSection(parsed, heading);
+}
+
+function readSection(parsed: ParsedMarkdown, heading: Heading): SectionRead {
+  const sectionLines = parsed.lines.slice(heading.startLine - 1, heading.endLine);
+  const truncated = truncateLines(sectionLines);
+  const nextLine = truncated.truncated ? heading.startLine + truncated.returnedLines : undefined;
+
+  return {
+    heading,
+    content: truncated.content,
+    truncated: truncated.truncated,
+    totalLines: heading.lineCount,
+    returnedLines: truncated.returnedLines,
+    nextLine: nextLine && nextLine <= heading.endLine ? nextLine : undefined,
+  };
+}
+
+function truncateLines(lines: string[]): { content: string; truncated: boolean; returnedLines: number } {
+  const selected: string[] = [];
+  let bytes = 0;
+  let truncated = false;
+
+  for (const line of lines) {
+    if (selected.length >= DEFAULT_MAX_SECTION_LINES) {
+      truncated = true;
+      break;
+    }
+
+    const separatorBytes = selected.length > 0 ? 1 : 0;
+    const lineBytes = encoder.encode(line).length;
+
+    if (bytes + separatorBytes + lineBytes > DEFAULT_MAX_SECTION_BYTES) {
+      const remainingBytes = DEFAULT_MAX_SECTION_BYTES - bytes - separatorBytes;
+      if (remainingBytes > 0) {
+        selected.push(truncateStringToBytes(line, remainingBytes));
+      }
+      truncated = true;
+      break;
+    }
+
+    selected.push(line);
+    bytes += separatorBytes + lineBytes;
+  }
+
+  if (selected.length < lines.length) truncated = true;
+
+  return {
+    content: selected.join("\n"),
+    truncated,
+    returnedLines: selected.length,
+  };
+}
+
+function truncateStringToBytes(value: string, maxBytes: number): string {
+  let result = "";
+  let bytes = 0;
+
+  for (const char of value) {
+    const charBytes = encoder.encode(char).length;
+    if (bytes + charBytes > maxBytes) break;
+    result += char;
+    bytes += charBytes;
+  }
+
+  return result;
+}

package/src/markdown/types.ts

@@ -0,0 +1,34 @@
+export interface Heading {
+  level: number;
+  title: string;
+  pathSlug: string;
+  startLine: number;
+  endLine: number;
+  lineCount: number;
+}
+
+export interface FrontmatterSummary {
+  pathSlug: "frontmatter";
+  keys: string[];
+  startLine: number;
+  endLine: number;
+  lineCount: number;
+}
+
+export interface ParsedMarkdown {
+  title?: string;
+  frontmatter?: FrontmatterSummary;
+  frontmatterKeys?: string[];
+  totalLines: number;
+  lines: string[];
+  headings: Heading[];
+}
+
+export interface SectionRead {
+  heading: Heading;
+  content: string;
+  truncated: boolean;
+  totalLines: number;
+  returnedLines: number;
+  nextLine?: number;
+}

package/src/tools/fs.ts

@@ -0,0 +1,136 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { TextDecoder } from "node:util";
+
+export interface MarkdownFile {
+  absolutePath: string;
+  displayPath: string;
+  text: string;
+}
+
+export function normalizeInputPath(inputPath: string, cwd: string): string {
+  const withoutAt = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
+  return isAbsolute(withoutAt) ? resolve(withoutAt) : resolve(cwd, withoutAt);
+}
+
+export async function readMarkdownText(inputPath: string, cwd: string): Promise<MarkdownFile> {
+  const absolutePath = normalizeInputPath(inputPath, cwd);
+  const stats = await stat(absolutePath).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cannot read Markdown file ${inputPath}: ${message}`);
+  });
+
+  if (stats.isDirectory()) {
+    throw new Error(`Cannot read Markdown file ${inputPath}: path is a directory`);
+  }
+
+  if (!stats.isFile()) {
+    throw new Error(`Cannot read Markdown file ${inputPath}: path is not a regular file`);
+  }
+
+  const buffer = await readFile(absolutePath);
+  if (buffer.includes(0)) {
+    throw new Error(`Cannot read Markdown file ${inputPath}: file appears to be binary`);
+  }
+
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+  } catch {
+    throw new Error(`Cannot read Markdown file ${inputPath}: file is not valid UTF-8`);
+  }
+
+  return {
+    absolutePath,
+    displayPath: displayPathFor(absolutePath, cwd),
+    text,
+  };
+}
+
+export async function listMarkdownFiles(inputPath: string, cwd: string, glob: string, maxFiles: number): Promise<{ root: string; files: string[]; truncated: boolean }> {
+  const root = normalizeInputPath(inputPath, cwd);
+  const stats = await stat(root).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cannot index Markdown path ${inputPath}: ${message}`);
+  });
+
+  if (stats.isFile()) {
+    return { root, files: [root], truncated: false };
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`Cannot index Markdown path ${inputPath}: path is not a file or directory`);
+  }
+
+  const matcher = globMatcher(glob);
+  const files: string[] = [];
+  let truncated = false;
+
+  async function visit(directory: string): Promise<void> {
+    if (files.length >= maxFiles) {
+      truncated = true;
+      return;
+    }
+
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        return;
+      }
+
+      if (entry.name === ".git" || entry.name === "node_modules" || entry.name === ".pi") continue;
+
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolute);
+      } else if (entry.isFile()) {
+        const rel = relative(root, absolute).split(sep).join("/");
+        if (matcher(rel)) files.push(absolute);
+      }
+    }
+  }
+
+  await visit(root);
+  return { root, files, truncated };
+}
+
+export function displayPathFor(absolutePath: string, cwd: string): string {
+  const relativePath = relative(cwd, absolutePath);
+  if (!relativePath.startsWith("..") && !isAbsolute(relativePath)) return relativePath || ".";
+  return absolutePath;
+}
+
+function globMatcher(glob: string): (relativePath: string) => boolean {
+  if (glob === "**/*.md") return (relativePath) => relativePath.endsWith(".md");
+  if (glob === "**/*.{md,markdown}") return (relativePath) => /\.(md|markdown)$/i.test(relativePath);
+
+  const regex = new RegExp(`^${escapeGlob(glob)}$`);
+  return (relativePath) => regex.test(relativePath);
+}
+
+function escapeGlob(glob: string): string {
+  let output = "";
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    const next = glob[index + 1];
+
+    if (char === "*" && next === "*") {
+      output += ".*";
+      index += 1;
+    } else if (char === "*") {
+      output += "[^/]*";
+    } else if (char === "?") {
+      output += "[^/]";
+    } else {
+      output += escapeRegex(char ?? "");
+    }
+  }
+  return output;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&");
+}

package/src/tools/markdown-index.ts

@@ -0,0 +1,60 @@
+import { Type } from "typebox";
+import { parseMarkdown } from "../markdown/parse.js";
+import { displayPathFor, listMarkdownFiles, readMarkdownText } from "./fs.js";
+
+export const markdownIndexParameters = Type.Object({
+  path: Type.String({ description: "Directory or Markdown file to index. A leading @ is ignored." }),
+  glob: Type.Optional(Type.String({ description: "Glob to match Markdown files. Defaults to **/*.md." })),
+  maxFiles: Type.Optional(Type.Number({ minimum: 1, maximum: 500, description: "Maximum files to index. Defaults to 100." })),
+  maxDepth: Type.Optional(Type.Number({ minimum: 1, maximum: 6, description: "Maximum heading depth to include. Defaults to 6." })),
+});
+
+export interface MarkdownIndexParams {
+  path: string;
+  glob?: string;
+  maxFiles?: number;
+  maxDepth?: number;
+}
+
+export function createMarkdownIndexTool() {
+  return {
+    name: "markdown_index",
+    label: "Markdown Index",
+    description: "Index a directory of Markdown files without reading full bodies. Returns file paths, line counts, frontmatter keys, and compact heading outlines.",
+    promptSnippet: "Index Markdown files in a directory without reading full bodies.",
+    promptGuidelines: [
+      "Use markdown_index to inspect folders of Markdown reports, notes, or generated artifacts before choosing files for markdown_outline and markdown_read.",
+    ],
+    parameters: markdownIndexParameters,
+
+    async execute(_toolCallId: string, params: MarkdownIndexParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: { cwd: string }) {
+      const maxFiles = Math.min(Math.max(Math.floor(params.maxFiles ?? 100), 1), 500);
+      const listing = await listMarkdownFiles(params.path, ctx.cwd, params.glob ?? "**/*.md", maxFiles);
+      const files = [];
+
+      for (const absolutePath of listing.files) {
+        const file = await readMarkdownText(absolutePath, ctx.cwd);
+        const parsed = parseMarkdown(file.text, { maxDepth: params.maxDepth, includeFrontmatter: true });
+        files.push({
+          path: displayPathFor(absolutePath, ctx.cwd),
+          title: parsed.title,
+          lineCount: parsed.totalLines,
+          headings: parsed.headings,
+          frontmatter: parsed.frontmatter,
+          frontmatterKeys: parsed.frontmatterKeys,
+        });
+      }
+
+      const output = {
+        root: displayPathFor(listing.root, ctx.cwd),
+        files,
+        truncated: listing.truncated,
+      };
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        details: output,
+      };
+    },
+  };
+}

package/src/tools/markdown-outline.ts

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+import { parseMarkdown } from "../markdown/parse.js";
+import { readMarkdownText } from "./fs.js";
+
+export const markdownOutlineParameters = Type.Object({
+  path: Type.String({ description: "Markdown file path. A leading @ is ignored." }),
+  maxDepth: Type.Optional(Type.Number({ minimum: 1, maximum: 6, description: "Maximum heading depth to include. Defaults to 6." })),
+  includeFrontmatter: Type.Optional(Type.Boolean({ description: "Include a bounded frontmatter summary. Defaults to true." })),
+});
+
+export interface MarkdownOutlineParams {
+  path: string;
+  maxDepth?: number;
+  includeFrontmatter?: boolean;
+}
+
+export function createMarkdownOutlineTool() {
+  return {
+    name: "markdown_outline",
+    label: "Markdown Outline",
+    description: "Extract a deterministic Markdown table of contents with heading levels, path slugs, line spans, and total line count.",
+    promptSnippet: "Extract a Markdown table of contents with heading levels, path slugs, line spans, and total line count.",
+    promptGuidelines: [
+      "Use markdown_outline before reading long Markdown files or generated reports.",
+    ],
+    parameters: markdownOutlineParameters,
+
+    async execute(_toolCallId: string, params: MarkdownOutlineParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: { cwd: string }) {
+      const file = await readMarkdownText(params.path, ctx.cwd);
+      const parsed = parseMarkdown(file.text, {
+        maxDepth: params.maxDepth,
+        includeFrontmatter: params.includeFrontmatter,
+      });
+
+      const output = {
+        path: file.displayPath,
+        title: parsed.title,
+        frontmatter: parsed.frontmatter,
+        totalLines: parsed.totalLines,
+        headings: parsed.headings,
+      };
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        details: output,
+      };
+    },
+  };
+}

package/src/tools/markdown-read.ts

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+import { parseMarkdown } from "../markdown/parse.js";
+import { readSectionByPathSlug } from "../markdown/sections.js";
+import { readMarkdownText } from "./fs.js";
+
+export const markdownReadParameters = Type.Object({
+  path: Type.String({ description: "Markdown file path. A leading @ is ignored." }),
+  sections: Type.Array(
+    Type.Object({
+      pathSlug: Type.String({ description: "Exact pathSlug returned by markdown_outline." }),
+    }),
+    { minItems: 1, description: "Sections to read by exact pathSlug." },
+  ),
+});
+
+export interface MarkdownReadParams {
+  path: string;
+  sections: Array<{ pathSlug: string }>;
+}
+
+export function createMarkdownReadTool() {
+  return {
+    name: "markdown_read",
+    label: "Markdown Read",
+    description: "Read one or more complete Markdown sections by exact pathSlug. Each section includes descendant subsections and is hard-truncated only for output safety.",
+    promptSnippet: "Read one or more Markdown sections by exact path slug.",
+    promptGuidelines: [
+      "Use markdown_read to inspect specific headings by pathSlug instead of guessing line ranges with read, head, tail, or sed. Always pass requested headings in a sections array, even for one section.",
+      "markdown_read only accepts exact pathSlug selectors from markdown_outline; call a subsection's own pathSlug when you only need that subsection.",
+    ],
+    parameters: markdownReadParameters,
+
+    async execute(_toolCallId: string, params: MarkdownReadParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: { cwd: string }) {
+      const file = await readMarkdownText(params.path, ctx.cwd);
+      const parsed = parseMarkdown(file.text);
+      const sections = params.sections.map((section) => readSectionByPathSlug(parsed, section.pathSlug));
+      const output = {
+        path: file.displayPath,
+        totalLines: parsed.totalLines,
+        sections,
+      };
+
+      return {
+        content: [{ type: "text", text: sections.map((section) => section.content).join("\n\n") }],
+        details: output,
+      };
+    },
+  };
+}