1 files changed, 515 insertions, 0 deletions
diff --git a/docs/mcp-prompts.md b/docs/mcp-prompts.md
new file mode 100644
index 0000000..23ce453
--- /dev/null
+++ b/docs/mcp-prompts.md
@@ -0,0 +1,515 @@
+# MCP Prompts Guide
+
+## Overview
+
+Prompts in hexai-mcp-server are reusable templates that can be parameterized with arguments. They're stored in JSONL format (one JSON object per line) for easy editing and version control.
+
+## Prompt Structure
+
+Each prompt has the following fields:
+
+```json
+{
+  "name": "code_review",
+  "title": "Request Code Review",
+  "description": "Analyzes code quality, style, and suggests improvements",
+  "arguments": [
+    {
+      "name": "code",
+      "description": "The code to review",
+      "required": true
+    }
+  ],
+  "messages": [
+    {
+      "role": "user",
+      "content": {
+        "type": "text",
+        "text": "Please review the following code:\n\n{{code}}"
+      }
+    }
+  ],
+  "tags": ["development", "review", "quality"],
+  "created": "2026-02-10T12:00:00Z",
+  "updated": "2026-02-10T12:00:00Z"
+}
+```
+
+### Field Descriptions
+
+- **name**: Unique identifier (alphanumeric + underscores only)
+- **title**: Human-readable display name
+- **description**: Brief explanation of what the prompt does
+- **arguments**: List of template variables (see below)
+- **messages**: Conversation messages with roles (user/assistant)
+- **tags**: Array of categorization tags for filtering
+- **created/updated**: ISO 8601 timestamps
+
+### Arguments
+
+Arguments define variables that can be substituted in message templates:
+
+```json
+{
+  "name": "variable_name",
+  "description": "What this variable represents",
+  "required": true
+}
+```
+
+- **name**: Variable name used in templates as `{{variable_name}}`
+- **description**: Help text for users
+- **required**: Whether the argument must be provided
+
+### Messages
+
+Messages define the conversation flow:
+
+```json
+{
+  "role": "user",
+  "content": {
+    "type": "text",
+    "text": "Prompt text with {{arguments}}"
+  }
+}
+```
+
+- **role**: Either `"user"` or `"assistant"`
+- **content.type**: Currently only `"text"` is supported
+- **content.text**: Message text with `{{argument}}` placeholders
+
+## Built-in Prompts
+
+hexai-mcp-server includes these built-in prompts:
+
+### code_review
+Analyzes code quality, style, and potential issues.
+
+**Arguments**:
+- `code` (required): The code to review
+
+**Tags**: development, review, quality
+
+### explain_code
+Provides detailed explanation of what code does.
+
+**Arguments**:
+- `code` (required): The code to explain
+
+**Tags**: development, documentation, learning
+
+### generate_tests
+Generates unit tests for a function or class.
+
+**Arguments**:
+- `code` (required): The code to test
+- `language` (optional): Programming language
+
+**Tags**: development, testing, tdd
+
+### document_function
+Generates documentation comments and docstrings.
+
+**Arguments**:
+- `code` (required): The code to document
+
+**Tags**: development, documentation
+
+### simplify_code
+Simplifies complex code while preserving behavior.
+
+**Arguments**:
+- `code` (required): The code to simplify
+
+**Tags**: development, refactoring, quality
+
+### fix_bugs
+Analyzes code for bugs and suggests fixes.
+
+**Arguments**:
+- `code` (required): The code to analyze
+- `error` (optional): Error message or symptoms
+
+**Tags**: development, debugging, bug-fix
+
+### refactor_extract
+Extracts code into a separate, reusable function.
+
+**Arguments**:
+- `code` (required): The code to extract
+- `function_name` (optional): Desired function name
+
+**Tags**: development, refactoring
+
+## Creating Custom Prompts
+
+### Storage Files
+
+Prompts are stored in two files:
+- `default.jsonl`: Built-in prompts (automatically created)
+- `user.jsonl`: Your custom prompts
+
+Both files are in: `~/.local/share/hexai/prompts/` (or your configured directory)
+
+### Method 1: Manual Editing
+
+Edit `user.jsonl` directly:
+
+```bash
+cd ~/.local/share/hexai/prompts/
+nano user.jsonl
+```
+
+Add a new prompt (one line, formatted for readability here):
+
+```json
+{"name":"optimize_sql","title":"Optimize SQL Query","description":"Analyzes and optimizes SQL queries for performance","arguments":[{"name":"query","description":"SQL query to optimize","required":true}],"messages":[{"role":"user","content":{"type":"text","text":"Optimize this SQL query:\n\n{{query}}\n\nSuggest improvements for:\n- Index usage\n- Query structure\n- Performance"}}],"tags":["database","optimization","sql"],"created":"2026-02-10T12:00:00Z","updated":"2026-02-10T12:00:00Z"}
+```
+
+**Tip**: Use a JSON formatter to validate:
+```bash
+cat user.jsonl | jq .
+```
+
+### Method 2: Python Script
+
+Create prompts programmatically:
+
+```python
+import json
+from datetime import datetime
+
+prompt = {
+    "name": "api_design",
+    "title": "Design REST API",
+    "description": "Designs a RESTful API endpoint with best practices",
+    "arguments": [
+        {
+            "name": "resource",
+            "description": "Resource name (e.g., 'users', 'posts')",
+            "required": True
+        },
+        {
+            "name": "operations",
+            "description": "Operations to support (e.g., 'CRUD')",
+            "required": False
+        }
+    ],
+    "messages": [
+        {
+            "role": "user",
+            "content": {
+                "type": "text",
+                "text": "Design a RESTful API for {{resource}}.\n\nOperations: {{operations}}\n\nInclude:\n- Endpoint paths\n- HTTP methods\n- Request/response formats\n- Status codes\n- Best practices"
+            }
+        }
+    ],
+    "tags": ["api", "design", "rest", "web"],
+    "created": datetime.now().isoformat(),
+    "updated": datetime.now().isoformat()
+}
+
+# Append to user.jsonl
+with open("~/.local/share/hexai/prompts/user.jsonl", "a") as f:
+    f.write(json.dumps(prompt) + "\n")
+```
+
+### Method 3: Go Code
+
+Use hexai's promptstore package:
+
+```go
+package main
+
+import (
+    "time"
+    "codeberg.org/snonux/hexai/internal/promptstore"
+)
+
+func main() {
+    store, _ := promptstore.NewJSONLStore("~/.local/share/hexai/prompts/")
+
+    prompt := &promptstore.Prompt{
+        Name:        "security_audit",
+        Title:       "Security Audit",
+        Description: "Audits code for security vulnerabilities",
+        Arguments: []promptstore.PromptArgument{
+            {Name: "code", Description: "Code to audit", Required: true},
+        },
+        Messages: []promptstore.PromptMessage{
+            {
+                Role: "user",
+                Content: promptstore.MessageContent{
+                    Type: "text",
+                    Text: "Audit this code for security issues:\n\n{{code}}",
+                },
+            },
+        },
+        Tags:    []string{"security", "audit", "vulnerability"},
+        Created: time.Now(),
+        Updated: time.Now(),
+    }
+
+    store.Create(prompt)
+}
+```
+
+## Template Syntax
+
+### Basic Substitution
+
+Use `{{argument_name}}` to insert argument values:
+
+```json
+{
+  "text": "Hello {{name}}! Your age is {{age}}."
+}
+```
+
+When rendered with `{"name": "Alice", "age": "30"}`:
+```
+Hello Alice! Your age is 30.
+```
+
+### Multi-line Templates
+
+Include newlines for formatting:
+
+```json
+{
+  "text": "Code Review Report\n\n## Code\n{{code}}\n\n## Analysis\nReviewing for quality..."
+}
+```
+
+### Optional Arguments
+
+Use default text for optional arguments in your description:
+
+```json
+{
+  "text": "Language: {{language}}\n\n(If not specified, will auto-detect)"
+}
+```
+
+## Best Practices
+
+### Naming Conventions
+
+- **name**: Use lowercase with underscores: `code_review`, `generate_tests`
+- **title**: Use Title Case: "Code Review", "Generate Tests"
+- **argument names**: Use lowercase: `code`, `language`, `function_name`
+
+### Description Guidelines
+
+- Keep descriptions concise (1-2 sentences)
+- Focus on what the prompt does, not how
+- Mention key capabilities or outputs
+
+Example:
+```
+✓ "Analyzes code for bugs and suggests fixes with explanations"
+✗ "This prompt will take your code and use AI to find bugs"
+```
+
+### Argument Guidelines
+
+- Mark arguments as `required: true` only if prompt can't work without them
+- Use descriptive names: `code` not `c`, `error_message` not `err`
+- Provide helpful descriptions for each argument
+
+### Message Design
+
+- Use clear, specific instructions
+- Include examples when helpful
+- Break complex requests into sections
+- Use formatting (headers, lists) for readability
+
+Example:
+```json
+{
+  "text": "Review this code:\n\n{{code}}\n\nFocus on:\n- Performance issues\n- Security vulnerabilities\n- Code style violations\n- Best practices"
+}
+```
+
+### Tags Strategy
+
+Use tags to categorize prompts:
+
+- **By language**: `go`, `python`, `javascript`, `rust`
+- **By domain**: `web`, `cli`, `api`, `database`
+- **By task**: `review`, `testing`, `documentation`, `refactoring`, `debugging`
+- **By difficulty**: `beginner`, `intermediate`, `advanced`
+
+Example tags:
+```json
+["go", "testing", "tdd", "unit-tests"]
+```
+
+## Example Prompts
+
+### Code Optimization
+
+```json
+{
+  "name": "optimize_algorithm",
+  "title": "Optimize Algorithm",
+  "description": "Analyzes algorithm complexity and suggests optimizations",
+  "arguments": [
+    {"name": "code", "description": "Algorithm implementation", "required": true},
+    {"name": "constraints", "description": "Performance constraints", "required": false}
+  ],
+  "messages": [
+    {
+      "role": "user",
+      "content": {
+        "type": "text",
+        "text": "Optimize this algorithm:\n\n{{code}}\n\nConstraints: {{constraints}}\n\nProvide:\n1. Time complexity analysis\n2. Space complexity analysis\n3. Optimization suggestions\n4. Optimized implementation"
+      }
+    }
+  ],
+  "tags": ["optimization", "performance", "algorithms"],
+  "created": "2026-02-10T12:00:00Z",
+  "updated": "2026-02-10T12:00:00Z"
+}
+```
+
+### API Endpoint Design
+
+```json
+{
+  "name": "design_endpoint",
+  "title": "Design API Endpoint",
+  "description": "Creates RESTful API endpoint specification",
+  "arguments": [
+    {"name": "resource", "description": "Resource name", "required": true},
+    {"name": "operations", "description": "CRUD operations needed", "required": true}
+  ],
+  "messages": [
+    {
+      "role": "user",
+      "content": {
+        "type": "text",
+        "text": "Design REST API endpoints for: {{resource}}\n\nOperations: {{operations}}\n\nSpecify:\n- Endpoint paths\n- HTTP methods\n- Request bodies\n- Response formats\n- Status codes\n- Authentication"
+      }
+    }
+  ],
+  "tags": ["api", "rest", "design", "web"],
+  "created": "2026-02-10T12:00:00Z",
+  "updated": "2026-02-10T12:00:00Z"
+}
+```
+
+## Sharing Prompts
+
+### Version Control
+
+Store prompts in git for team collaboration:
+
+```bash
+cd ~/.local/share/hexai/prompts/
+git init
+git add user.jsonl
+git commit -m "Add custom prompts"
+git remote add origin https://github.com/myteam/hexai-prompts
+git push -u origin main
+```
+
+### Team Setup
+
+Team members clone the repository:
+
+```bash
+git clone https://github.com/myteam/hexai-prompts ~/hexai-prompts
+export HEXAI_MCP_PROMPTS_DIR=~/hexai-prompts
+```
+
+### Updating Shared Prompts
+
+```bash
+cd ~/hexai-prompts
+# Edit user.jsonl
+git commit -am "Add SQL optimization prompt"
+git push
+```
+
+## Troubleshooting
+
+### Invalid JSON Format
+
+**Error**: Prompt not appearing or parse warnings in logs
+
+**Solution**: Validate JSON:
+```bash
+cat user.jsonl | jq . >/dev/null
+# If errors, fix JSON syntax
+```
+
+### Duplicate Name
+
+**Error**: "prompt already exists"
+
+**Solution**: Prompts must have unique names. Change the name or delete the old prompt.
+
+### Template Not Rendering
+
+**Issue**: `{{argument}}` appears literally in output
+
+**Cause**: Argument name mismatch
+
+**Solution**: Ensure argument names match exactly (case-sensitive):
+```json
+"arguments": [{"name": "code", ...}]
+"text": "{{code}}"  // ✓ Correct
+"text": "{{Code}}"  // ✗ Won't work
+```
+
+### Missing Required Argument
+
+**Error**: "missing required argument: X"
+
+**Solution**: Provide all required arguments when using the prompt in your client.
+
+## Advanced Topics
+
+### Multi-Turn Conversations
+
+Include both user and assistant messages for context:
+
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "content": {"type": "text", "text": "What is {{topic}}?"}
+    },
+    {
+      "role": "assistant",
+      "content": {"type": "text", "text": "Let me explain {{topic}} in detail..."}
+    },
+    {
+      "role": "user",
+      "content": {"type": "text", "text": "Now apply this to: {{code}}"}
+    }
+  ]
+}
+```
+
+### Conditional Logic
+
+Use description to guide usage:
+
+```json
+{
+  "description": "If 'language' is not provided, will auto-detect",
+  "text": "Language: {{language}}\n\n(Auto-detect if empty)"
+}
+```
+
+The MCP protocol doesn't support conditional logic in templates, but you can document expected behavior.
+
+## See Also
+
+- [MCP Setup Guide](mcp-setup.md)
+- [hexai Configuration](configuration.md)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)