Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

docs(v2): add AI Development section — llms.txt, MCP, and skills pages (#802)

Jakub Sieradzkibc9ee62a0fc6
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
index 5a29641d4..0a5838761 100644
--- a/.github/workflows/claude-code-review.yml
+++ b/.github/workflows/claude-code-review.yml
@@ -2,7 +2,7 @@ name: Claude Code Review
on:
pull_request:
- types: [opened, synchronize]
+ types: [opened, synchronize, ready_for_review, reopened]
# Optional: Only run on specific file changes
# paths:
# - "src/**/*.ts"
@@ -27,26 +27,17 @@ jobs:
steps:
- name: Checkout repository
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Run Claude Code Review
id: claude-review
- uses: anthropics/claude-code-action@d59651bd82c48d81756854675ce4fa4d69722200 # v1
+ uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- prompt: |
- REPO: ${{ github.repository }}
- PR NUMBER: ${{ github.event.pull_request.number }}
- Please review this pull request and provide feedback on:
- - Code quality and best practices
- - Potential bugs or issues
- - Performance considerations
- - Security concerns
- - Test coverage
- Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
- Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+ plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+ plugins: 'code-review@claude-code-plugins'
+ prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
- # or https://code.claude.com/docs/en/cli-reference for available options
- claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
\ No newline at end of file
+ # or https://code.claude.com/docs/en/cli-reference for available options
\ No newline at end of file
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 6ae9a7b1c..fe0942625 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -83,6 +83,14 @@
"v2/migrations/from-1-x-to-2-0"
]
},
+ {
+ "group": "AI Development",
+ "pages": [
+ "v2/ai-development/llms",
+ "v2/ai-development/mcp",
+ "v2/ai-development/skills"
+ ]
+ },
{
"group": "Legal",
"pages": [
diff --git a/apps/docs/v2/ai-development/llms.mdx b/apps/docs/v2/ai-development/llms.mdx
new file mode 100644
index 000000000..5ba87c957
--- /dev/null
+++ b/apps/docs/v2/ai-development/llms.mdx
@@ -0,0 +1,70 @@
+---
+title: "LLMs"
+description: "Feed Mercur documentation directly to LLMs for accurate, context-aware assistance."
+---
+
+# LLMs
+
+Mercur documentation is optimized for Large Language Models using the [llms.txt standard](https://llmstxt.org). This gives AI tools a structured map of all documentation — so they can answer technical questions accurately instead of guessing.
+
+Think of it like a sitemap, but for AI: a machine-readable file that describes what documentation exists, how it's organized, and where to find specific topics.
+
+---
+
+## Available files
+
+### llms.txt
+
+A structured index of all Mercur documentation pages with descriptions and links.
+
+```
+https://docs.mercurjs.com/llms.txt
+```
+
+Use this when your AI tool supports llms.txt natively or when you want to give it an overview of what's available without sending the full content.
+
+### llms-full.txt
+
+The entire Mercur documentation compiled into a single plain-text file.
+
+```
+https://docs.mercurjs.com/llms-full.txt
+```
+
+Use this when you want to give an LLM the complete context in one shot — ideal for complex questions that span multiple topics.
+
+---
+
+## How to use
+
+<Tabs>
+ <Tab title="Claude Projects">
+ 1. Open [Claude](https://claude.ai) and create a new Project
+ 2. In project knowledge, add a URL: `https://docs.mercurjs.com/llms-full.txt`
+ 3. Claude now has full Mercur documentation context in every conversation within that project
+ </Tab>
+ <Tab title="ChatGPT">
+ 1. Download `https://docs.mercurjs.com/llms-full.txt`
+ 2. Upload it as a file in your conversation or attach it to a Custom GPT's knowledge base
+ </Tab>
+ <Tab title="AI IDE (paste)">
+ For any AI coding tool that accepts context:
+ 1. Fetch the file: `curl -o mercur-docs.txt https://docs.mercurjs.com/llms-full.txt`
+ 2. Attach it to your conversation or project context
+ </Tab>
+</Tabs>
+
+<Tip>
+ Both files are auto-generated and always reflect the latest documentation. No maintenance required.
+</Tip>
+
+---
+
+## When to use llms.txt vs MCP
+
+| Approach | Best for |
+|----------|----------|
+| **llms.txt / llms-full.txt** | One-time context loading, tools without MCP support, offline use |
+| **[MCP Server](/v2/ai-development/mcp)** | Live search, always up-to-date results, integrated AI environments |
+
+For the best experience, use the [MCP server](/v2/ai-development/mcp) if your tool supports it. Fall back to llms.txt when MCP isn't available.
diff --git a/apps/docs/v2/ai-development/mcp.mdx b/apps/docs/v2/ai-development/mcp.mdx
new file mode 100644
index 000000000..450b25df8
--- /dev/null
+++ b/apps/docs/v2/ai-development/mcp.mdx
@@ -0,0 +1,151 @@
+---
+title: "MCP Server"
+description: "Connect your AI environment to Mercur documentation via Model Context Protocol."
+---
+
+# MCP Server
+
+Mercur exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI tools **search Mercur documentation directly**. Instead of relying on training data that may be outdated, your AI assistant queries the actual docs in real time.
+
+```
+https://docs.mercurjs.com/mcp
+```
+
+---
+
+## Available tool
+
+### SearchMercurJsDocumentation
+
+Searches across all Mercur documentation and returns:
+
+- Relevant excerpts matching your query
+- Page titles for context
+- Direct links to documentation pages
+
+Use it when you need to look up API references, understand how a module works, find CLI commands, or retrieve examples during development.
+
+---
+
+## Connect to your AI environment
+
+<Tabs>
+ <Tab title="Cursor">
+ <Steps>
+ <Step title="Open MCP settings">
+ 1. Press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>
+ 2. Search for **Open MCP settings**
+ 3. Select **Add custom MCP**
+ </Step>
+ <Step title="Configure the server">
+ Add the following to your `mcp.json`:
+
+ ```json
+ {
+ "mcpServers": {
+ "mercur": {
+ "url": "https://docs.mercurjs.com/mcp"
+ }
+ }
+ }
+ ```
+ </Step>
+ <Step title="Use it">
+ Restart Cursor and ask: **"Search Mercur docs for how to add a block"**
+ </Step>
+ </Steps>
+
+ See [Cursor MCP docs](https://docs.cursor.com/en/context/mcp) for more.
+ </Tab>
+ <Tab title="VS Code">
+ <Steps>
+ <Step title="Create MCP config">
+ Create a file at `.vscode/mcp.json` in your project root.
+ </Step>
+ <Step title="Configure the server">
+ ```json
+ {
+ "servers": {
+ "mercur": {
+ "type": "http",
+ "url": "https://docs.mercurjs.com/mcp"
+ }
+ }
+ }
+ ```
+ </Step>
+ <Step title="Use it">
+ Open the Copilot Chat panel and ask: **"List available MCP servers."**
+ </Step>
+ </Steps>
+
+ See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more.
+ </Tab>
+ <Tab title="Windsurf">
+ <Steps>
+ <Step title="Open MCP config">
+ 1. Press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>
+ 2. Search for **Open Windsurf MCP Configuration**
+ </Step>
+ <Step title="Configure the server">
+ ```json
+ {
+ "mcpServers": {
+ "mercur": {
+ "serverUrl": "https://docs.mercurjs.com/mcp"
+ }
+ }
+ }
+ ```
+ </Step>
+ <Step title="Use it">
+ Open Cascade and ask: **"Search Mercur docs for seller setup"**
+ </Step>
+ </Steps>
+ </Tab>
+ <Tab title="Claude">
+ <Steps>
+ <Step title="Add the MCP server">
+ 1. Go to Claude → Settings → **Connectors**
+ 2. Select **Add custom connector**
+ 3. Enter:
+ - **Name**: Mercur
+ - **URL**: `https://docs.mercurjs.com/mcp`
+ 4. Save
+ </Step>
+ <Step title="Use it">
+ In chat, click the **attachments (+)** button and select your Mercur MCP connector.
+ </Step>
+ </Steps>
+
+ See [Claude connector docs](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server) for more.
+ </Tab>
+ <Tab title="Claude Code">
+ <Steps>
+ <Step title="Install the MCP server">
+ ```bash
+ claude mcp add --transport http mercur https://docs.mercurjs.com/mcp
+ ```
+ </Step>
+ <Step title="Verify installation">
+ ```bash
+ claude mcp list
+ ```
+ </Step>
+ <Step title="Use it">
+ Claude Code can now query Mercur documentation directly during any conversation.
+ </Step>
+ </Steps>
+
+ See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more.
+ </Tab>
+</Tabs>
+
+---
+
+## When to use MCP vs llms.txt
+
+| Approach | Best for |
+|----------|----------|
+| **MCP Server** | Live search, always up-to-date, integrated environments |
+| **[llms.txt](/v2/ai-development/llms)** | Full context dump, tools without MCP, offline use |
diff --git a/apps/docs/v2/ai-development/skills.mdx b/apps/docs/v2/ai-development/skills.mdx
new file mode 100644
index 000000000..201be376a
--- /dev/null
+++ b/apps/docs/v2/ai-development/skills.mdx
@@ -0,0 +1,210 @@
+---
+title: "Skills"
+description: "Pre-built AI workflows that ship with every Mercur project for safe, guided development."
+---
+
+# Skills
+
+Every Mercur project created with `@mercurjs/cli@latest create` includes a set of **skills** — reusable prompt modules that teach your AI coding tool how to work with Mercur correctly.
+
+Skills encode domain knowledge, enforce patterns, and catch common mistakes. Instead of prompting your AI with "please follow the Mercur conventions for forms", the skill handles it automatically.
+
+---
+
+## How skills work
+
+Skills are markdown files in your project's `.claude/skills/` directory. They're loaded by [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (and compatible tools) in two ways:
+
+- **Slash command** — type `/skill-name` to invoke a skill explicitly
+- **Auto-trigger** — the AI detects that your task matches a skill's description and loads it automatically
+
+Each skill contains rules, checklists, and workflows tailored to a specific aspect of Mercur development.
+
+---
+
+## Included skills
+
+Every project created from the Mercur starter template includes these skills:
+
+| Skill | What it does | When it triggers |
+|-------|-------------|-----------------|
+| `mercur-cli` | Guides correct usage of CLI commands (`create`, `init`, `add`, `search`, `view`, `diff`) | Working with the Mercur CLI |
+| `mercur-blocks` | Discovers, evaluates, installs, and verifies blocks using `blocks.json` aliases | Adding or updating blocks |
+| `migration-guide` | Analyzes a 1.x project and walks through migration to 2.0 step by step | Upgrading from Mercur 1.x |
+| `dashboard-page-ui` | Enforces correct routing, page composition, and i18n for dashboard pages | Building admin or vendor pages |
+| `dashboard-form-ui` | Enforces form structure, validation, submission guards, and UI conventions | Building forms in dashboards |
+| `dashboard-tab-ui` | Enforces tab structure, validation scope, and wizard conventions | Adding tabs to multi-step forms |
+| `medusa-ui-conformance` | Keeps custom UI aligned with `@medusajs/ui` patterns and local wrappers | Adding reusable UI components |
+
+---
+
+## Using skills
+
+### Invoke explicitly
+
+Type the slash command in Claude Code:
+
+```
+/mercur-blocks
+```
+
+The skill loads its full context and guides you through the workflow.
+
+### Let it auto-trigger
+
+Just describe your task naturally:
+
+```
+Add the reviews block to my project
+```
+
+Claude Code matches this to the `mercur-blocks` skill and activates it automatically.
+
+### Pass arguments
+
+Some skills accept arguments:
+
+```
+/migration-guide /path/to/old-project
+```
+
+---
+
+## Where skills live
+
+```
+your-project/
+└── .claude/
+ └── skills/
+ ├── mercur-cli/
+ │ └── SKILL.md
+ ├── mercur-blocks/
+ │ └── SKILL.md
+ ├── dashboard-page-ui/
+ │ └── SKILL.md
+ ├── dashboard-form-ui/
+ │ └── SKILL.md
+ ├── dashboard-tab-ui/
+ │ └── SKILL.md
+ ├── medusa-ui-conformance/
+ │ └── SKILL.md
+ └── migration-guide/
+ └── SKILL.md
+```
+
+Each skill is a directory containing a `SKILL.md` file with frontmatter metadata and the skill content.
+
+---
+
+## Creating custom skills
+
+You can create your own skills to encode project-specific patterns and workflows.
+
+### 1. Create the skill directory
+
+```bash
+mkdir -p .claude/skills/my-custom-skill
+```
+
+### 2. Write the skill file
+
+Create `.claude/skills/my-custom-skill/SKILL.md`:
+
+```markdown
+---
+name: my-custom-skill
+description: One sentence describing when this skill should trigger.
+---
+
+# My Custom Skill
+
+Use this skill when:
+- [trigger condition 1]
+- [trigger condition 2]
+
+## Rules
+
+- [rule 1]
+- [rule 2]
+
+## Workflow
+
+1. [step 1]
+2. [step 2]
+```
+
+### 3. Key conventions
+
+- **Directory name** must be `kebab-case` and match the `name` in frontmatter
+- **File** must be named `SKILL.md` (uppercase)
+- **Description** is the primary trigger — write it clearly so the AI knows when to activate
+- Keep skills focused on one domain; split broad skills into smaller ones
+
+### Frontmatter options
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | Yes | Must match directory name |
+| `description` | Yes | Primary trigger — AI uses this to decide relevance |
+| `allowed-tools` | No | Restrict available tools (e.g., `Read, Grep, Glob` for review-only skills) |
+| `argument-hint` | No | Hint shown in slash command menu (e.g., `"[block-name]"`) |
+
+<Tip>
+ Start with just `name` and `description`. Add other fields only when they change runtime behavior.
+</Tip>
+
+---
+
+## Using skills with other AI tools
+
+Skills ship in `.claude/skills/` by default, but they're plain markdown files — any AI coding tool that reads project-level prompts can use them. The recommended approach is to use a shared `.ai/skills/` directory as the canonical source and symlink from each tool's config directory.
+
+### OpenAI Codex
+
+Codex reads skills from `.codex/skills/`. Symlink to the shared directory:
+
+```bash
+# Option A: symlink from .claude/skills (what ships with the template)
+mkdir -p .codex
+ln -s ../.claude/skills .codex/skills
+
+# Option B: if you've set up a shared .ai/skills/ directory
+mkdir -p .codex
+ln -s ../.ai/skills .codex/skills
+```
+
+Codex picks up the same `SKILL.md` files and triggers them the same way.
+
+### Cursor
+
+Cursor reads project rules from `.cursor/rules/`. You can convert skills to Cursor rules:
+
+```bash
+mkdir -p .cursor/rules
+# Copy a skill as a Cursor rule
+cp .claude/skills/mercur-blocks/SKILL.md .cursor/rules/mercur-blocks.md
+```
+
+Cursor rules use a similar markdown format — the skill content works as-is, though Cursor-specific frontmatter fields (like `globs`) can be added for file-pattern triggering.
+
+### Shared directory pattern
+
+For projects where multiple team members use different AI tools, set up a shared canonical directory:
+
+```bash
+# 1. Create shared directory
+mkdir -p .ai/skills
+
+# 2. Move skills there
+mv .claude/skills/* .ai/skills/
+
+# 3. Symlink from each tool
+ln -sf ../.ai/skills .claude/skills
+ln -sf ../.ai/skills .codex/skills
+```
+
+This ensures all tools see the same skills with no content duplication. Update skills in `.ai/skills/` and every tool gets the change.
+
+<Tip>
+ Skills are markdown — they work with any AI tool that supports project-level context. If your tool doesn't have a conventional directory, you can paste skill content into custom instructions or system prompts.
+</Tip>
diff --git a/apps/docs/v2/blocks.mdx b/apps/docs/v2/blocks.mdx
new file mode 100644
index 000000000..e1088b56d
--- /dev/null
+++ b/apps/docs/v2/blocks.mdx
@@ -0,0 +1,138 @@
+---
+title: "Official Blocks"
+sidebarTitle: "Official Blocks"
+description: "Modular blocks from the official Mercur registry — install only what you need."
+mode: "custom"
+---
+
+<div className="max-w-5xl mx-auto px-6 py-16">
+
+ <div className="mb-12">
+ <h1 className="text-4xl font-bold tracking-tight mb-4">Official Blocks</h1>
+ <p className="text-lg text-gray-500 dark:text-gray-400 max-w-2xl mb-6">
+ Blocks are modular pieces of marketplace functionality — API routes, workflows, UI pages, and data models. Each block is copied directly into your project. You own the code.
+ </p>
+ <div className="inline-flex items-center gap-3 px-4 py-2.5 rounded-lg border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800">
+ <code className="text-sm font-mono text-gray-800 dark:text-gray-100">bunx @mercurjs/cli@latest add &lt;block-name&gt;</code>
+ </div>
+ </div>
+
+ <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">⭐</span>
+ <h3 className="font-semibold text-base m-0">reviews</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Product and seller reviews with ratings, customer/vendor/admin API routes, and workflows.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">admin</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">👥</span>
+ <h3 className="font-semibold text-base m-0">team-management</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Team member management with invitations, roles, and vendor portal pages.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">🔖</span>
+ <h3 className="font-semibold text-base m-0">wishlist</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Customer wishlist with product bookmarking, pricing context, and store API endpoints.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">🔔</span>
+ <h3 className="font-semibold text-base m-0">vendor-notifications</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Vendor notification feed with bell icon in the navbar and a vendor API endpoint.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">🔍</span>
+ <h3 className="font-semibold text-base m-0">algolia</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Algolia search integration with product indexing, event-driven sync, and store search API.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">module</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">✅</span>
+ <h3 className="font-semibold text-base m-0">requests</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">Admin approval system for entity requests — list, review, accept or reject submissions.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">admin</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">📦</span>
+ <h3 className="font-semibold text-base m-0">product-import-export</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">CSV product import & export for vendors. Includes API routes, workflows, and portal drawers.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">workflow</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ <div className="p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <div className="flex items-center gap-3 mb-1">
+ <span className="text-base">💬</span>
+ <h3 className="font-semibold text-base m-0">vendor-chat</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">TalkJS chat integration for vendors — API endpoint for seller conversations and a Messages page.</p>
+ <div className="flex flex-wrap gap-1.5">
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">api</span>
+ <span className="text-xs text-gray-500 dark:text-gray-400 bg-gray-100 dark:bg-gray-800 rounded px-2 py-0.5">vendor</span>
+ </div>
+ </div>
+
+ </div>
+
+ <div className="mt-10 p-5 rounded-xl border border-gray-200 dark:border-gray-800">
+ <p className="text-sm text-gray-500 dark:text-gray-400 m-0">
+ Blocks are copied directly into your project — no runtime dependencies on Mercur.
+ After installing, follow the setup steps in the <a href="/v2/developer-guide/blocks" className="text-gray-900 dark:text-gray-100 font-medium underline underline-offset-2">Developer Guide</a>.
+ Want to build your own? See the <a href="/v2/developer-guide/registry" className="text-gray-900 dark:text-gray-100 font-medium underline underline-offset-2">Registry Guide</a>.
+ </p>
+ </div>
+
+</div>
diff --git a/apps/docs/v2/getting-started/introduction.mdx b/apps/docs/v2/getting-started/introduction.mdx
index dccd3bf95..1a11afebd 100644
--- a/apps/docs/v2/getting-started/introduction.mdx
+++ b/apps/docs/v2/getting-started/introduction.mdx
@@ -41,11 +41,19 @@ Most AI coding tools generate loose snippets that you have to wire together your
Here's what that looks like in practice:
-- **Adding features via CLI** — An AI agent can run `npx @mercurjs/cli@latest add reviews` to install a complete review system — data models, API routes, workflows, and UI — in one command. No guessing at file structure or imports. The CLI handles wiring automatically.
+- **Adding features via CLI** — An AI agent can run `bunx @mercurjs/cli@latest add reviews` to install a complete review system — data models, API routes, workflows, and UI — in one command. No guessing at file structure or imports. The CLI handles wiring automatically.
- **Extending workflows without rebuilding them** — Need custom logic when an order is placed? AI can hook into the existing `complete-cart-with-split-orders` workflow and inject a step — without rewriting the entire cart flow. Medusa's workflow hooks make this safe and predictable.
-- **Generating typed integrations** — AI reads the generated route types from `npx @mercurjs/cli@latest codegen` and produces API calls that are correct by construction. No hallucinated endpoints, no wrong payloads — the types are the source of truth.
+- **Generating typed integrations** — AI reads the generated route types from `bunx @mercurjs/cli@latest codegen` and produces API calls that are correct by construction. No hallucinated endpoints, no wrong payloads — the types are the source of truth.
- **Building UI pages** — AI can scaffold an admin or vendor page by creating a file in `src/routes/`. The dashboard SDK picks it up automatically through file-based routing. No manual route registration, no config files to update.
-- **Modifying blocks it can diff** — AI can compare local code against the registry with `npx @mercurjs/cli@latest diff`, understand what changed, and make targeted modifications instead of blind overwrites.
+- **Modifying blocks it can diff** — AI can compare local code against the registry with `bunx @mercurjs/cli@latest diff`, understand what changed, and make targeted modifications instead of blind overwrites.
+
+### Connect your AI tools
+
+To start building with AI, connect your environment to Mercur's knowledge base:
+
+- **[LLMs](/v2/ai-development/llms)** — Feed the full Mercur documentation to any LLM via `llms.txt`
+- **[MCP Server](/v2/ai-development/mcp)** — Let your AI tool search Mercur docs in real time (Cursor, VS Code, Claude, Claude Code)
+- **[Skills](/v2/ai-development/skills)** — Pre-built AI workflows that ship with every Mercur project for guided development
### Why this matters
diff --git a/apps/docs/v2/welcome.mdx b/apps/docs/v2/welcome.mdx
index 04e36fbee..773d63c6b 100644
--- a/apps/docs/v2/welcome.mdx
+++ b/apps/docs/v2/welcome.mdx
@@ -71,6 +71,17 @@ mode: "custom"
<h3 className="font-semibold text-base mb-2">Discord</h3>
<p className="text-sm text-gray-500 dark:text-gray-400 m-0">Join the community for help, discussions, and updates.</p>
</a>
+ <a href="/v2/blocks" className="block p-5 rounded-xl border border-gray-200 dark:border-gray-800 hover:border-gray-300 dark:hover:border-gray-700 hover:bg-gray-50 dark:hover:bg-gray-900 transition-all no-underline">
+ <div className="flex items-center gap-3 mb-2">
+ <span className="text-lg">🧱</span>
+ <h3 className="font-semibold text-base m-0">Browse Blocks</h3>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-gray-400 m-0">Official registry blocks — install only what you need.</p>
+ </a>
+ <a href="/v2/ai-development/llms" className="block p-5 rounded-xl border border-gray-200 dark:border-gray-800 hover:border-gray-300 dark:hover:border-gray-700 hover:bg-gray-50 dark:hover:bg-gray-900 transition-all no-underline">
+ <h3 className="font-semibold text-base mb-2">AI Development</h3>
+ <p className="text-sm text-gray-500 dark:text-gray-400 m-0">LLMs, MCP server, and skills — connect your AI tools to Mercur.</p>
+ </a>
</div>
</div>
</div>