markstream-vue 0.0.9 → 0.0.10-beta.0

package/.agents/skills/markstream-custom-components/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: markstream-custom-components
+description: Override built-in Markstream node renderers and add trusted custom tags. Use when Codex needs to apply `setCustomComponents`, keep overrides scoped with `customId`, map override keys like `image`, `code_block`, `mermaid`, or `link`, or wire `customHtmlTags` and nested renderers for tags such as `thinking`.
+---
+
+# Markstream Custom Components
+
+Use this skill when the task is to change how Markstream renders specific nodes or custom tags.
+
+Read [references/patterns.md](references/patterns.md) before choosing an override strategy.
+
+## Workflow
+
+1. Classify the request.
+   - `built-in override`: replace an existing renderer such as `image`, `link`, `code_block`, `mermaid`, `d2`, or `inline_code`.
+   - `custom tag`: support trusted HTML-like tags such as `thinking`.
+   - `parser-level`: requires token transforms or AST reshaping. Only then should you leave this skill and use low-level parser hooks.
+2. Prefer scoped mappings.
+   - Use `setCustomComponents(customId, mapping)` instead of global mappings whenever practical.
+   - Pass the same `customId` or `custom-id` to the renderer instance.
+3. Start with the smallest safe override.
+   - Leaf-like nodes (`image`, `link`, `inline_code`, `mermaid`) are easier than container nodes (`heading`, `paragraph`, `list_item`).
+   - If the request only changes Mermaid, use `mermaid`, not `code_block`.
+4. Preserve nested Markdown when needed.
+   - For trusted custom tags with inner Markdown, render `node.content` with a nested renderer.
+   - Pass the same custom-tag allowlist to nested renderers.
+5. Keep props and cleanup intact.
+   - Preserve `node`, `loading`, `indexKey`, `customId`, and `isDark`.
+   - Remove temporary scoped mappings with `removeCustomComponents(customId)` when the scope is no longer needed.
+6. Validate with the smallest useful check.
+   - Prefer a local demo, targeted test, or docs build.
+   - Call out whether the implementation is safe for repeated and nested custom tags.
+
+## Default Decisions
+
+- Scoped overrides first, global overrides only when the whole app truly needs them.
+- Leaf-node overrides before container-node overrides.
+- `customHtmlTags` plus scoped custom components before parser hooks.
+- Nested renderers for tag bodies that contain Markdown.
+
+## Useful Doc Targets
+
+- `docs/guide/component-overrides.md`
+- `docs/guide/custom-components.md`
+- `docs/guide/components.md`
+- `docs/guide/advanced.md`

package/.agents/skills/markstream-custom-components/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Markstream Custom Components"
+  short_description: "Override Markstream nodes and add trusted custom tags"
+  default_prompt: "Use $markstream-custom-components to add scoped Markstream overrides or trusted custom tags in this repository."

package/.agents/skills/markstream-custom-components/references/patterns.md

@@ -0,0 +1,31 @@
+# Override Patterns
+
+## Common override keys
+
+| Key | Typical use |
+|-----|-------------|
+| `image` | lightboxes, captions, lazy-loading wrappers |
+| `link` | analytics, router integration, custom tooltip behavior |
+| `code_block` | replace regular fenced code blocks |
+| `mermaid` | customize Mermaid only |
+| `d2` | customize D2 only |
+| `infographic` | customize infographic blocks only |
+| `inline_code` | typography or special inline behavior |
+| `heading`, `paragraph`, `list_item` | container overrides that must render children |
+
+## Trusted custom-tag pattern
+
+1. register the tag in `customHtmlTags`
+2. map the same tag name with `setCustomComponents(customId, { tagName: Component })`
+3. if the tag body contains Markdown, render `node.content` with a nested renderer
+4. pass the same `customHtmlTags` list to the nested renderer
+
+## Nested renderer defaults
+
+- `typewriter: false`
+- `viewportPriority: false`
+- `deferNodesUntilVisible: false`
+- `maxLiveNodes: 0`
+- `batchRendering: false`
+
+Use those defaults when predictable nested streaming behavior matters more than optimization.

package/.agents/skills/markstream-install/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: markstream-install
+description: Install and wire markstream-vue, markstream-react, markstream-vue2, or markstream-angular into an existing repository. Use when Codex needs to choose the right package, install the smallest peer-dependency set, fix CSS/reset order, decide between `content` and `nodes`, or add a minimal working renderer example.
+---
+
+# Markstream Install
+
+Use this skill when the task is "add markstream to an app" or "fix a broken markstream install".
+
+Read [references/scenarios.md](references/scenarios.md) before making dependency choices.
+
+## Workflow
+
+1. Detect the target framework and CSS stack.
+   - Check `package.json`, app entry files, Tailwind or UnoCSS config, and whether the repo is SSR or streaming-focused.
+   - Choose the package that matches the host app: `markstream-vue`, `markstream-vue2`, `markstream-react`, or `markstream-angular`.
+2. Install the smallest peer set that matches the requested features.
+   - Add peers only for features the user actually needs: Monaco, Mermaid, D2, KaTeX, or Shiki.
+   - Do not install every optional peer by default.
+3. Fix CSS order.
+   - Put reset styles before Markstream styles.
+   - In Tailwind or UnoCSS projects, place `markstream-*/index.css` inside `@layer components`.
+   - Import `katex/dist/katex.min.css` when math is enabled.
+4. Add the smallest working render example.
+   - Use `content` for static or low-frequency rendering.
+   - Use `nodes` plus `final` when the app receives streaming updates.
+5. Keep customization scoped.
+   - If the task requires overrides, prefer `customId` / `custom-id` plus scoped `setCustomComponents(...)`.
+6. Validate.
+   - Run the smallest relevant build, typecheck, test, or docs build command.
+   - Report which peers were installed, where CSS lives, and whether the repo should later adopt `nodes`.
+
+## Default Decisions
+
+- Prefer the minimal peer set over "install everything".
+- Prefer `content` unless the app is clearly SSE, chat, token-streaming, or worker-preparsed.
+- Treat CSS order as a first-class part of installation, not a later cleanup.
+- When the request includes SSR, explicitly gate browser-only peers behind client-only boundaries.
+
+## Useful Doc Targets
+
+- `docs/guide/installation.md`
+- `docs/guide/usage.md`
+- `docs/guide/troubleshooting.md`
+- `docs/guide/component-overrides.md`

package/.agents/skills/markstream-install/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Markstream Install"
+  short_description: "Install markstream with the right peers and CSS order"
+  default_prompt: "Use $markstream-install to add the correct Markstream package to this repository with the smallest peer-dependency set."

package/.agents/skills/markstream-install/references/scenarios.md

@@ -0,0 +1,33 @@
+# Install Scenarios
+
+## Package selection
+
+| Host app | Package |
+|----------|---------|
+| Vue 3 / Nuxt 3 | `markstream-vue` |
+| Vue 2.6 / 2.7 | `markstream-vue2` |
+| React 18+ | `markstream-react` |
+| Angular 20+ | `markstream-angular` |
+
+## Peer selection
+
+| Feature | Peers |
+|---------|-------|
+| Lightweight highlighted code blocks | `shiki`, `stream-markdown` |
+| Monaco-powered code blocks | `stream-monaco` |
+| Mermaid | `mermaid` |
+| D2 | `@terrastruct/d2` |
+| KaTeX math | `katex` |
+
+## CSS checklist
+
+- reset first
+- Markstream CSS after reset
+- in Tailwind or UnoCSS projects, keep Markstream CSS inside `@layer components`
+- import KaTeX CSS when math is used
+- when standalone node components are rendered directly, wrap them with `.markstream-vue`
+
+## Input choice
+
+- `content`: docs pages, static articles, low-frequency updates
+- `nodes` + `final`: SSE, token streaming, AI chat, worker-preparsed content

package/.agents/skills/markstream-migration/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: markstream-migration
+description: Audit and migrate existing Markdown rendering to Markstream. Use when Codex needs to replace another renderer, classify direct vs custom vs plugin-heavy usage, preserve behavior during adoption, migrate custom renderers into scoped Markstream overrides, or decide when `nodes` streaming is worth adopting.
+---
+
+# Markstream Migration
+
+Use this skill when a repo already renders Markdown and the task is to adopt Markstream safely.
+
+Read [references/adoption-checklist.md](references/adoption-checklist.md) before changing code.
+
+## Workflow
+
+1. Audit the repo's current renderer usage.
+   - Search for markdown renderers, plugin chains, raw HTML handling, security props, and custom renderers.
+   - List every call site that will be touched.
+2. Classify the migration.
+   - `direct`: simple string-in renderer swap.
+   - `renderer-custom`: custom renderers but limited parser work.
+   - `plugin-heavy`: remark, rehype, markdown-it, or other transform-heavy pipelines.
+   - `security-heavy`: allow or deny lists, URL rewriting, sanitization, or raw HTML policies.
+3. Swap the renderer first.
+   - Introduce the correct Markstream package and CSS.
+   - Preserve user-visible behavior before adding richer Markstream-only features.
+4. Migrate custom renderers.
+   - Convert tag-based renderers into node-type overrides with scoped `setCustomComponents`.
+   - For trusted tag-like content, prefer `customHtmlTags`.
+5. Review gaps honestly.
+   - Do not claim 1:1 parity where none exists.
+   - Call out parser, plugin, security, or HTML behavior that still needs manual review.
+6. Treat streaming as a second pass unless clearly required now.
+   - Move to `nodes` only when the app receives streaming or high-frequency updates.
+7. Validate and summarize.
+   - Run the smallest relevant tests or build.
+   - Report direct mappings, TODOs, and remaining verification work.
+
+## Default Decisions
+
+- Renderer swap first, streaming optimization second.
+- Preserve safety over feature parity when HTML or security rules are involved.
+- Prefer explicit TODOs over vague claims.
+- Recommend against migration when the current stack depends heavily on transforms that Markstream does not mirror directly.
+
+## Useful Doc Targets
+
+- `docs/guide/react-markdown-migration.md`
+- `docs/guide/react-markdown-migration-cookbook.md`
+- `docs/guide/installation.md`
+- `docs/guide/component-overrides.md`
+- `docs/guide/advanced.md`

package/.agents/skills/markstream-migration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Markstream Migration"
+  short_description: "Audit and migrate existing Markdown rendering to Markstream"
+  default_prompt: "Use $markstream-migration to audit this repository's current Markdown renderer and migrate it to the appropriate Markstream package."

package/.agents/skills/markstream-migration/references/adoption-checklist.md

@@ -0,0 +1,30 @@
+# Adoption Checklist
+
+## Audit queries
+
+- `react-markdown`
+- `remarkPlugins`
+- `rehypePlugins`
+- `markdown-it`
+- `marked`
+- `rehypeRaw`
+- `skipHtml`
+- `allowedElements`
+- `disallowedElements`
+- `allowElement`
+- `urlTransform`
+- custom renderers and wrapper components
+
+## Classification guide
+
+- `direct`: plain renderer swap, little or no custom behavior
+- `renderer-custom`: existing custom renderers can become Markstream node overrides
+- `plugin-heavy`: large transform chains need manual review
+- `security-heavy`: HTML policies and URL rewriting need explicit review
+
+## Migration defaults
+
+- swap the renderer package first
+- keep CSS order correct before debugging visual differences
+- move to scoped `setCustomComponents` instead of global mutations
+- only adopt `nodes` if the app is streaming or frequently re-parsing

package/README.md

@@ -25,6 +25,7 @@ Looking for other frameworks?
 ## Contents
 
 - [TL;DR Highlights](#tldr-highlights)
+- [Choose Your Path](#choose-your-path)
 - [Try It Now](#-try-it-now)
 - [Community & support](#-community--support)
 - [Quick Start](#-quick-start)
@@ -56,6 +57,17 @@ Looking for other frameworks?
 - Works with **raw Markdown strings or pre-parsed nodes**, supports **custom Vue components** inline.
 - TypeScript-first, ship-ready defaults — import CSS and render.
 
+## Choose Your Path
+
+| If you want to... | Start here | Then go to |
+| --- | --- | --- |
+| get the first render on screen | [Quick Start](#-quick-start) | [Installation guide](https://markstream-vue-docs.simonhe.me/guide/installation) |
+| integrate it into a docs site or VitePress theme | [Docs Site & VitePress](https://markstream-vue-docs.simonhe.me/guide/vitepress-docs-integration) | [Custom Tags & Advanced Components](https://markstream-vue-docs.simonhe.me/guide/custom-components) |
+| build an AI chat UI or SSE stream | [AI Chat & Streaming](https://markstream-vue-docs.simonhe.me/guide/ai-chat-streaming) | [Performance](https://markstream-vue-docs.simonhe.me/guide/performance) |
+| replace one built-in renderer | [Override Built-in Components](https://markstream-vue-docs.simonhe.me/guide/component-overrides) | [Renderer & Node Components](https://markstream-vue-docs.simonhe.me/guide/components) |
+| add trusted tags such as `thinking` | [Custom Tags & Advanced Components](https://markstream-vue-docs.simonhe.me/guide/custom-components) | [API Reference](https://markstream-vue-docs.simonhe.me/guide/api) |
+| debug a broken integration but do not know why yet | [Troubleshooting by Symptom](https://markstream-vue-docs.simonhe.me/guide/troubleshooting-path) | [Troubleshooting](https://markstream-vue-docs.simonhe.me/guide/troubleshooting) |
+
 ## 🚀 Try It Now
 
 - Playground (interactive demo): https://markstream-vue.simonhe.me/
@@ -68,6 +80,37 @@ Looking for other frameworks?
 - Nuxt playground: `pnpm play:nuxt`
 - Discord: https://discord.gg/vkzdkjeRCW
 
+## CLI helpers for skills and prompts
+
+If you want the packaged AI assets without cloning the repo:
+
+```bash
+npx skills add Simon-He95/markstream-vue
+npx markstream-vue skills list
+npx markstream-vue skills install
+npx markstream-vue prompts list
+npx markstream-vue prompts show install-markstream
+```
+
+Recommended usage:
+
+- `npx skills add Simon-He95/markstream-vue` is the primary path for Codex-compatible skill discovery because it reads `.agents/skills` directly from the GitHub repository
+- `skills install` installs the bundled skills into your agent skill directory (default: `~/.agents/skills`)
+- `prompts list` and `prompts show` to discover and copy maintained prompt templates
+
+Other `npx skills add` forms also work:
+
+```bash
+# Full GitHub URL
+npx skills add https://github.com/Simon-He95/markstream-vue
+
+# Direct path to one skill in this repo
+npx skills add https://github.com/Simon-He95/markstream-vue/tree/main/.agents/skills/markstream-install
+
+# Any git URL
+npx skills add git@github.com:Simon-He95/markstream-vue.git
+```
+
 ## 💬 Community & support
 
 - Discussions: https://github.com/Simon-He95/markstream-vue/discussions
@@ -76,6 +119,14 @@ Looking for other frameworks?
 
 The test page gives you an editor + live preview plus “generate share link” that encodes the input in the URL (with a fallback to open directly or pre-fill a GitHub Issue for long payloads).
 
+## Support the project
+
+If markstream-vue helps your work, you can support ongoing maintenance with one of these QR codes.
+
+| Alipay | WeChat Pay |
+| --- | --- |
+| <img src="https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/zhifubao.jpg" alt="Alipay QR code" width="240" /> | <img src="https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/weixin.jpg" alt="WeChat Pay QR code" width="240" /> |
+
 ## ⚡ Quick Start
 
 ```bash

package/README.zh-CN.md

@@ -25,6 +25,7 @@
 ## 目录
 
 - [速览](#速览)
+- [按场景选择入口](#按场景选择入口)
 - [立即试用](#-立即试用)
 - [社区与支持](#-社区与支持)
 - [快速上手](#-快速上手)
@@ -57,6 +58,17 @@
 - 同时支持 **Markdown 字符串或预解析节点**，可在 Markdown 中嵌入 **自定义 Vue 组件**。
 - TypeScript 优先，开箱默认即可上线（导入 CSS 即用）。
 
+## 按场景选择入口
+
+| 如果你现在想做的是... | 先看这里 | 然后看 |
+| --- | --- | --- |
+| 先把第一段渲染跑起来 | [快速上手](#-快速上手) | [安装指南](https://markstream-vue-docs.simonhe.me/zh/guide/installation) |
+| 接到文档站或 VitePress 主题里 | [文档站与 VitePress 集成](https://markstream-vue-docs.simonhe.me/zh/guide/vitepress-docs-integration) | [自定义标签与高级组件](https://markstream-vue-docs.simonhe.me/zh/guide/custom-components) |
+| 做 AI 聊天界面或 SSE 流式输出 | [AI 聊天与流式输出](https://markstream-vue-docs.simonhe.me/zh/guide/ai-chat-streaming) | [性能](https://markstream-vue-docs.simonhe.me/zh/guide/performance) |
+| 替换一个内置节点渲染器 | [覆盖内置组件](https://markstream-vue-docs.simonhe.me/zh/guide/component-overrides) | [渲染器与节点组件](https://markstream-vue-docs.simonhe.me/zh/guide/components) |
+| 增加 `thinking` 这类可信标签 | [自定义标签与高级组件](https://markstream-vue-docs.simonhe.me/zh/guide/custom-components) | [API 参考](https://markstream-vue-docs.simonhe.me/zh/guide/api) |
+| 接入坏了但还不知道原因 | [按症状排查](https://markstream-vue-docs.simonhe.me/zh/guide/troubleshooting-path) | [排查问题](https://markstream-vue-docs.simonhe.me/zh/guide/troubleshooting) |
+
 ## 🚀 立即试用
 
 - Playground（交互演示）： https://markstream-vue.simonhe.me/
@@ -69,6 +81,37 @@
 - Nuxt playground：`pnpm play:nuxt`
 - Discord： https://discord.gg/vkzdkjeRCW
 
+## skills 和 prompts 的 CLI
+
+如果你想直接拿到打包后的 AI 资产，而不是先克隆仓库：
+
+```bash
+npx skills add Simon-He95/markstream-vue
+npx markstream-vue skills list
+npx markstream-vue skills install
+npx markstream-vue prompts list
+npx markstream-vue prompts show install-markstream
+```
+
+推荐这样理解：
+
+- `npx skills add Simon-He95/markstream-vue` 是最推荐的安装方式，因为它会直接读取 GitHub 仓库里的 `.agents/skills`
+- `skills install` 会把打包好的 skills 安装到你的 agent skills 目录，默认是 `~/.agents/skills`
+- `prompts list` / `prompts show` 用来发现并直接复制官方维护的 prompt 模板
+
+`npx skills add` 也支持这些来源：
+
+```bash
+# 完整 GitHub URL
+npx skills add https://github.com/Simon-He95/markstream-vue
+
+# 仓库里的单个 skill 直链
+npx skills add https://github.com/Simon-He95/markstream-vue/tree/main/.agents/skills/markstream-install
+
+# 任意 git URL
+npx skills add git@github.com:Simon-He95/markstream-vue.git
+```
+
 ## 💬 社区与支持
 
 - Discussions：https://github.com/Simon-He95/markstream-vue/discussions
@@ -77,6 +120,14 @@
 
 测试页内置编辑器 + 实时预览，并提供“生成分享链接”功能（过长内容会回退为直接打开或预填 GitHub Issue）。
 
+## 支持项目
+
+如果 markstream-vue 对你的工作有帮助，欢迎通过下面的收款码支持项目的持续维护。
+
+| 支付宝 | 微信收款 |
+| --- | --- |
+| <img src="https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/zhifubao.jpg" alt="支付宝收款码" width="240" /> | <img src="https://raw.githubusercontent.com/Simon-He95/markstream-vue/main/docs/public/sponsor/weixin.jpg" alt="微信收款码" width="240" /> |
+
 ## ⚡ 快速上手
 
 ```bash

package/bin/markstream-vue.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { defaultPromptsRoot, listPromptNames, readPrompt } from './prompts-lib.mjs'
+import {
+  listSkillNames,
+  parseInstallArgs,
+  printInstallHelp,
+  printInstallSummary,
+  runSkillsInstall,
+} from './skills-lib.mjs'
+
+function printCliHelp() {
+  console.log(`Usage: markstream-vue <command>
+
+Commands:
+  skills list                 List bundled skills
+  skills install [options]    Install bundled skills
+  prompts list                List bundled prompt templates
+  prompts dir                 Print bundled prompt directory
+  prompts show <name>         Print a bundled prompt template
+
+Examples:
+  markstream-vue skills list
+  markstream-vue skills install
+  markstream-vue skills install --target codex
+  markstream-vue skills install --mode copy --force
+  markstream-vue prompts list
+  markstream-vue prompts show install-markstream
+`)
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const [namespace, action, ...rest] = argv
+
+  if (!namespace || namespace === '--help' || namespace === '-h' || namespace === 'help') {
+    printCliHelp()
+    return
+  }
+
+  if (namespace === 'prompts') {
+    if (!action || action === 'help') {
+      console.log(`Usage: markstream-vue prompts <list|dir|show> [name]
+
+Examples:
+  markstream-vue prompts list
+  markstream-vue prompts dir
+  markstream-vue prompts show install-markstream
+`)
+      return
+    }
+
+    if (action === 'list') {
+      const promptNames = await listPromptNames()
+      console.log(`Bundled prompts (${promptNames.length}):`)
+      for (const promptName of promptNames)
+        console.log(`- ${promptName}`)
+      return
+    }
+
+    if (action === 'dir') {
+      console.log(defaultPromptsRoot)
+      return
+    }
+
+    if (action === 'show') {
+      const [promptName] = rest
+      const { content } = await readPrompt(promptName)
+      process.stdout.write(content)
+      if (!content.endsWith('\n'))
+        process.stdout.write('\n')
+      return
+    }
+
+    throw new Error(`Unknown prompts action: ${action}`)
+  }
+
+  if (namespace !== 'skills') {
+    throw new Error(`Unknown command namespace: ${namespace}`)
+  }
+
+  if (!action || action === 'help') {
+    printInstallHelp('markstream-vue skills install', 'copy')
+    return
+  }
+
+  if (action === 'list') {
+    const skillNames = await listSkillNames()
+    console.log(`Bundled skills (${skillNames.length}):`)
+    for (const skillName of skillNames)
+      console.log(`- ${skillName}`)
+    return
+  }
+
+  if (action === 'install') {
+    const args = parseInstallArgs(rest, {
+      target: 'agents',
+      mode: 'copy',
+    })
+    if (args.help) {
+      printInstallHelp('markstream-vue skills install', 'copy')
+      return
+    }
+    const result = await runSkillsInstall(args)
+    printInstallSummary(result)
+    return
+  }
+
+  throw new Error(`Unknown skills action: ${action}`)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/bin/prompts-lib.mjs

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+export const packageRoot = path.resolve(__dirname, '..')
+export const defaultPromptsRoot = path.join(packageRoot, 'prompts')
+
+export async function listPromptFiles(promptsRoot = defaultPromptsRoot) {
+  const dirents = await fs.readdir(promptsRoot, { withFileTypes: true })
+  return dirents
+    .filter(dirent => dirent.isFile() && dirent.name.endsWith('.md'))
+    .map(dirent => dirent.name)
+    .sort()
+}
+
+export async function listPromptNames(promptsRoot = defaultPromptsRoot) {
+  return (await listPromptFiles(promptsRoot)).map(file => file.replace(/\.md$/i, ''))
+}
+
+export async function resolvePromptPath(name, promptsRoot = defaultPromptsRoot) {
+  const normalized = String(name ?? '').trim()
+  if (!normalized)
+    throw new Error('Prompt name is required')
+
+  const candidates = normalized.endsWith('.md')
+    ? [normalized]
+    : [`${normalized}.md`, normalized]
+
+  for (const candidate of candidates) {
+    const fullPath = path.join(promptsRoot, candidate)
+    try {
+      await fs.access(fullPath)
+      return fullPath
+    }
+    catch {
+      // continue
+    }
+  }
+
+  const available = await listPromptNames(promptsRoot)
+  throw new Error(`Unknown prompt: ${normalized}. Available prompts: ${available.join(', ')}`)
+}
+
+export async function readPrompt(name, promptsRoot = defaultPromptsRoot) {
+  const fullPath = await resolvePromptPath(name, promptsRoot)
+  const content = await fs.readFile(fullPath, 'utf8')
+  return { fullPath, content }
+}