markstream-vue 0.0.9 → 0.0.10-beta.1

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

@@ -0,0 +1,34 @@
+---
+name: markstream-angular
+description: Integrate markstream-angular into an Angular app. Use when Codex needs standalone component imports, signal-based examples, CSS wiring, custom HTML tags or customComponents setup, or optional peer integration in an Angular repository.
+---
+
+# Markstream Angular
+
+Use this skill when the host app is Angular and the task is to adopt the Angular package cleanly.
+
+## Workflow
+
+1. Confirm the repo is Angular.
+2. Install `markstream-angular` plus only the requested optional peers.
+3. Import `markstream-angular/index.css` from the app shell.
+   - Add `katex/dist/katex.min.css` when math is enabled.
+4. Prefer standalone Angular integration.
+   - Use `MarkstreamAngularComponent` in `imports` and keep examples signal-friendly.
+5. Start with `[content]`.
+   - Use `[final]`, `[codeBlockStream]`, and other streaming inputs only when the UI actually streams.
+6. Use `[customHtmlTags]` and `[customComponents]` for trusted tag workflows.
+7. Validate with the smallest useful Angular dev or build command.
+
+## Default Decisions
+
+- Standalone Angular first, NgModule-era patterns only when the repo still depends on them.
+- Treat streaming flags as opt-in.
+- Keep optional peers minimal and explicit.
+
+## Useful Doc Targets
+
+- `docs/guide/angular-quick-start.md`
+- `docs/guide/angular-installation.md`
+- `docs/guide/playground.md`
+- `docs/guide/troubleshooting.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Angular
+  short_description: Install and wire markstream-angular in Angular apps
+  default_prompt: 'Use $markstream-angular to integrate markstream-angular into this Angular repository with the right CSS, optional peers, and standalone setup.'

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/.agents/skills/markstream-nuxt/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: markstream-nuxt
+description: Integrate markstream-vue into a Nuxt 3 or Nuxt 4 app. Use when Codex needs client-only boundaries, SSR-safe setup, browser-only peer gating, worker-aware initialization, or a safe `MarkdownRender` integration inside pages, components, or Nuxt plugins.
+---
+
+# Markstream Nuxt
+
+Use this skill when the host app is Nuxt and SSR boundaries matter.
+
+## Workflow
+
+1. Confirm the repo is Nuxt 3 or 4.
+2. Install `markstream-vue` plus only the optional peers required by the requested features.
+3. Keep browser-only peers behind client-only boundaries.
+   - Prefer `<client-only>` wrappers, `.client` plugins, or guarded setup paths.
+4. Import `markstream-vue/index.css` from a client-safe app shell or plugin.
+5. Start with `content`, and move to `nodes` plus `final` only when the UI is streaming.
+6. Validate with the smallest relevant Nuxt dev, build, or typecheck command.
+
+## Default Decisions
+
+- SSR safety comes before feature completeness.
+- Avoid import-time access to browser globals from server code paths.
+- Treat Monaco, Mermaid workers, and similar heavy peers as client-only unless the repo already has a proven SSR pattern.
+
+## Useful Doc Targets
+
+- `docs/nuxt-ssr.md`
+- `docs/guide/installation.md`
+- `docs/guide/usage.md`
+- `docs/guide/troubleshooting.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Nuxt
+  short_description: Wire markstream-vue safely in a Nuxt SSR app
+  default_prompt: Use $markstream-nuxt to add markstream-vue to this Nuxt app with safe client-only boundaries and the right optional peers.

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

@@ -0,0 +1,33 @@
+---
+name: markstream-react
+description: Integrate markstream-react into a React 18+ or Next app. Use when Codex needs to add the React renderer, import CSS correctly, choose between `content` and `nodes`, keep Next client boundaries safe, convert renderer overrides, or prepare a repo for `react-markdown` migration.
+---
+
+# Markstream React
+
+Use this skill when the host app is React or Next and the task is to wire Markstream safely.
+
+## Workflow
+
+1. Confirm the repo is React, Next, or another React-based host.
+2. Install `markstream-react` plus only the requested optional peers.
+3. Import `markstream-react/index.css` from the app shell or client entry.
+4. Start with `content`.
+   - Move to `nodes` plus `final` only when the UI receives streaming or high-frequency updates.
+5. Respect SSR boundaries in Next.
+   - Prefer `use client`, dynamic imports with `ssr: false`, or other client-only boundaries when browser-only peers are involved.
+6. Use scoped Markstream overrides before custom parser work.
+7. Validate with the smallest useful dev, build, or typecheck command.
+
+## Default Decisions
+
+- Renderer wiring first, migration cleanup second.
+- If the repo already uses `react-markdown`, pair this skill with `markstream-migration`.
+- Prefer the smallest client-only boundary that solves the SSR issue.
+
+## Useful Doc Targets
+
+- `docs/guide/react-quick-start.md`
+- `docs/guide/react-installation.md`
+- `docs/guide/react-markdown-migration.md`
+- `docs/guide/component-overrides.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream React
+  short_description: Install and wire markstream-react in React or Next
+  default_prompt: Use $markstream-react to integrate markstream-react into this React or Next repository with safe client boundaries and the right optional peers.

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

@@ -0,0 +1,32 @@
+---
+name: markstream-vue
+description: Integrate markstream-vue into a Vue 3 app. Use when Codex needs to add the Vue 3 renderer, import CSS in the right order, choose between `content` and `nodes`, enable optional peers like Mermaid, KaTeX, D2, Monaco, or Shiki, or wire scoped custom components in a non-Nuxt Vue repository.
+---
+
+# Markstream Vue 3
+
+Use this skill when the host app is plain Vue 3, typically Vite-based, and not Nuxt.
+
+## Workflow
+
+1. Confirm the repo is Vue 3 and not Nuxt.
+2. Install `markstream-vue` plus only the optional peers required by the requested features.
+3. Import `markstream-vue/index.css` after resets.
+   - In Tailwind or UnoCSS projects, keep Markstream styles inside `@layer components`.
+4. Start with `<MarkdownRender :content="markdown" />`.
+   - Switch to `nodes` plus `final` only for streaming, SSE, or high-frequency updates.
+5. Use `custom-id` plus scoped `setCustomComponents(...)` for overrides.
+6. Validate with the smallest useful dev, build, or typecheck command.
+
+## Default Decisions
+
+- Vue 3 apps default to `content`.
+- Prefer local component registration unless the repo already uses a shared plugin entry.
+- If the host is actually Nuxt, leave SSR-specific setup to `markstream-nuxt`.
+
+## Useful Doc Targets
+
+- `docs/guide/quick-start.md`
+- `docs/guide/installation.md`
+- `docs/guide/usage.md`
+- `docs/guide/component-overrides.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Vue 3
+  short_description: Install and wire markstream-vue in a Vue 3 app
+  default_prompt: Use $markstream-vue to integrate markstream-vue into this Vue 3 repository with the right CSS order and optional peers.

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

@@ -0,0 +1,32 @@
+---
+name: markstream-vue2
+description: Integrate markstream-vue2 into a Vue 2.6 or 2.7 app. Use when Codex needs Vue 2-compatible setup, `@vue/composition-api` decisions, CSS wiring, optional peer setup, or scoped Markstream overrides in a Vue 2 repository that is not specifically Vue CLI / Webpack 4 constrained.
+---
+
+# Markstream Vue 2
+
+Use this skill when the host app is Vue 2 and not specifically a Vue CLI / Webpack 4 edge case.
+
+## Workflow
+
+1. Confirm the repo is Vue 2.6 or 2.7.
+2. Install `markstream-vue2`.
+   - Add `@vue/composition-api` only when the repo is Vue 2.6 and uses Composition API patterns.
+3. Import `markstream-vue2/index.css` after resets.
+4. Start with `<MarkdownRender :content="markdown" />`.
+5. Use scoped custom component mappings when the task needs overrides or trusted tags.
+6. Validate with the smallest useful dev or build command.
+
+## Default Decisions
+
+- Vue 2.7 can use built-in Composition API support.
+- Vue 2.6 needs `@vue/composition-api` only when the codebase actually relies on Composition API.
+- If the repo is Vue CLI / Webpack 4, prefer `markstream-vue2-cli`.
+- If the repo is Vue 2 plus Vite worker imports, prefer `markstream-vue2-vite`.
+
+## Useful Doc Targets
+
+- `docs/guide/vue2-quick-start.md`
+- `docs/guide/vue2-installation.md`
+- `docs/guide/vue2-components.md`
+- `docs/guide/troubleshooting.md`

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Vue 2
+  short_description: Install and wire markstream-vue2 in a Vue 2 app
+  default_prompt: 'Use $markstream-vue2 to integrate markstream-vue2 into this Vue 2 repository with the right CSS, optional peers, and Composition API setup.'

package/.agents/skills/markstream-vue2-cli/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: markstream-vue2-cli
+description: Integrate markstream-vue2 into a Vue 2 Vue CLI or Webpack 4 app. Use when Codex needs Webpack 4-friendly setup, CDN worker fallbacks for Mermaid or KaTeX, `dist/index.css` imports, Vue 2 composition-api shims, or safer code block defaults that avoid fragile Monaco worker setups.
+---
+
+# Markstream Vue 2 CLI
+
+Use this skill when the host app is Vue 2 on Vue CLI or another Webpack 4-style stack.
+
+## Workflow
+
+1. Confirm the repo uses Vue 2 plus Vue CLI or Webpack 4-era tooling.
+2. Install `markstream-vue2` and only the peers required for the requested features.
+3. Import `markstream-vue2/dist/index.css` in the app shell.
+4. Avoid Vite-style `?worker` imports.
+   - Use `createKaTeXWorkerFromCDN(...)` and `createMermaidWorkerFromCDN(...)` when workers are needed.
+5. Prefer stable code block defaults over brittle Monaco wiring.
+   - `MarkdownCodeBlockNode` plus `stream-markdown` is safer than Monaco in Webpack 4-era repos.
+6. Validate with the smallest useful local dev or build command.
+
+## Default Decisions
+
+- Treat Monaco and worker-heavy setups as opt-in and fragile on Webpack 4.
+- Prefer CDN workers over bundler workers for Mermaid and KaTeX.
+- Keep the Vue 2 composition-api shim explicit when the repo is on Vue 2.6.
+
+## Useful Doc Targets
+
+- `docs/guide/vue2-quick-start.md`
+- `docs/guide/vue2-installation.md`
+- `docs/guide/troubleshooting.md`

package/.agents/skills/markstream-vue2-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Vue 2 CLI
+  short_description: Wire markstream-vue2 in Vue CLI / Webpack 4 apps
+  default_prompt: Use $markstream-vue2-cli to add markstream-vue2 to this Vue CLI or Webpack 4 app with CDN workers and Webpack-safe defaults.

package/.agents/skills/markstream-vue2-vite/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: markstream-vue2-vite
+description: Integrate markstream-vue2 into a Vue 2 plus Vite app. Use when Codex needs Vite-friendly worker imports, `?worker` or `?worker&inline` setup for Mermaid or KaTeX, modern CSS ordering, or Vue 2 compatibility in a Vite-based repository.
+---
+
+# Markstream Vue 2 Vite
+
+Use this skill when the host app is Vue 2 and the bundler is Vite.
+
+## Workflow
+
+1. Confirm the repo is Vue 2 with Vite-based tooling.
+2. Install `markstream-vue2` plus only the requested optional peers.
+3. Import `markstream-vue2/index.css` after resets.
+4. Use Vite worker imports when the repo needs bundled workers.
+   - `markstream-vue2/workers/... ?worker` or `?worker&inline` patterns are allowed here.
+5. Keep Composition API decisions explicit for Vue 2.6 repos.
+6. Validate with the smallest useful Vite dev or build command.
+
+## Default Decisions
+
+- Prefer bundled workers over CDN workers in Vite-based Vue 2 repos.
+- Keep UnoCSS or Tailwind resets before Markstream CSS.
+- Use the generic `markstream-vue2` skill only when the bundler-specific choice does not matter.
+
+## Useful Doc Targets
+
+- `docs/guide/vue2-quick-start.md`
+- `docs/guide/vue2-installation.md`
+- `docs/guide/tailwind.md`
+- `docs/guide/troubleshooting.md`

package/.agents/skills/markstream-vue2-vite/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: Markstream Vue 2 Vite
+  short_description: 'Wire markstream-vue2 in Vue 2 + Vite apps'
+  default_prompt: Use $markstream-vue2-vite to integrate markstream-vue2 into this Vue 2 Vite repository with Vite-friendly worker setup.

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