docs: for prompts, import and env variables

Author: butschster

docs/.vitepress/config.mts

@@ -43,7 +43,8 @@ export default withMermaid({
                 text: 'MCP Server',
                 items: [
                     {text: 'Integration', link: '/mcp-server'},
-                    {text: 'Filesystem', link: '/mcp/filesystem'}
+                    {text: 'Filesystem', link: '/mcp/filesystem'},
+                    {text: 'Prompts', link: '/mcp/propmts'}
                 ]
             },
             {

docs/configuration.md

@@ -111,7 +111,8 @@ As you can see it's pretty simple.
 
 ## Configuration Imports
 
-For large projects with multiple components or services, you can split your configuration across multiple files using the import functionality.
+For large projects with multiple components or services, you can split your configuration across multiple files using
+the import functionality.
 
 - Import paths are resolved relative to the importing file
 - You can apply path prefixes to source paths in imported configurations
@@ -157,4 +158,14 @@ documents:
     }
   ]
 }
-```
+```
+
+## Using Environment Variables
+
+Context Generator supports configuration via environment variables, which provides a flexible way to override settings
+without modifying your main configuration files.
+
+### Setting Up
+
+1. Create a `.env` file in your project root directory
+2. Add configuration variables using `KEY=VALUE` format

docs/getting-started/command-reference.md

@@ -57,14 +57,16 @@ Creates a new configuration file in the current directory. The default filename
 ctx init
 ```
 
-You can also specify a different file type [Supported types: `yaml`, `json`]:
+You can also specify a different filename (e.g., `context.json`. By default, it will create `context.yaml`):
 
 ```bash
-ctx init --type=json
+ctx init --config-file=context.json
 # or
-ctx init -t json
+ctx init -t context.json
 ```
 
+> **Note**: Only `php`, `json`, and `yaml` formats are supported for the configuration file.
+
 ## Check Version
 
 Checks for available updates by comparing your version with the latest release on GitHub, and provides update
@@ -96,10 +98,10 @@ ctx update
 ctx u
 ```
 
-If you installed the PHAR file in a non-standard location, you can specify the path:
+If you installed ctx in a non-standard location, you can specify the path:
 
 ```bash
-ctx self-update --phar-path=/usr/local/bin/ctx
+ctx self-update --path=/usr/local/bin/ctx
 # or
 ctx self-update -p /usr/local/bin/ctx
 ```

docs/index.md

@@ -34,6 +34,12 @@ When working with AI-powered development tools context is everything.
   custom explanations. Use AI to generate user guides, API references, or developer documentation based on your actual
   code.
 
+- **Reusable Prompt Libraries:** Create, share, and import collections of specialized prompts for common development
+  tasks. Build once, use everywhere, and leverage the community's expertise without reinventing the wheel.
+
+- **Standardized Team Workflows:** Establish consistent AI interaction patterns across your team by sharing prompt
+  libraries that encode best practices and domain expertise for your specific projects.
+
 - **Seamless AI Integration**: With MCP support, [connect](/mcp-server) Claude AI directly to your codebase, allowing
   for real-time, context-aware assistance without manual context sharing.
 
@@ -43,6 +49,7 @@ When working with AI-powered development tools context is everything.
 2. Targets specific files through pattern matching, content search, size, or date filters
 3. Applies optional modifiers (like extracting PHP signatures without implementation details)
 4. Organizes content into well-structured markdown documents
-5. Saves context files ready to be shared with LLMs
-6. Optionally serves context through an MCP server, allowing AI assistants like Claude to directly access project
+5. Provides pre-defined prompts for common tasks that can be imported, shared, and reused
+6. Saves context files ready to be shared with LLMs
+7. Optionally serves context through an MCP server, allowing AI assistants like Claude to directly access project
    information

docs/mcp-server.md

@@ -150,4 +150,24 @@ When connected via MCP, Claude has access to the following tools:
 - `file-write`: Write content to a file with optional directory creation
 - `file-rename`: Rename a file or directory
 - `file-move`: Move a file to a different location
-- `file-info`: Get detailed information about a file or directory
+- `file-info`: Get detailed information about a file or directory
+
+## Environment Variables
+
+You can configure the MCP server using environment variables.
+
+### Configuring Document Names
+
+You can customize how document names appear in Claude's interface.
+
+```dotenv
+CTX_DOCUMENT_NAME_FORMAT="{description} ({tags}) - {path}"
+```
+
+Available placeholders:
+
+- `{path}` - The document's output path
+- `{description}` - The document description
+- `{tags}` - Comma-separated list of document tags
+
+By default, the format is: `[{path}] {description}`

docs/mcp/prompts.md

@@ -0,0 +1,132 @@
+# Prompts
+
+MCP server includes support for pre-defined prompts that provide structured conversation templates. These
+prompts can serve as starting points for common tasks, code generation, or project-specific workflows.
+
+## How Prompts Work
+
+Prompts are defined in your configuration files and can include:
+
+- Template messages with variable placeholders
+- Input schemas for required and optional parameters
+- Descriptions for better discoverability
+
+When LLM requests a prompt, the MCP server returns the structured conversation template with any variable
+placeholders filled in based on the provided arguments.
+
+## Defining Prompts
+
+```yaml
+prompts:
+  - id: generate-controller
+    description: "Generate a controller for a specific entity"
+    schema:
+      properties:
+        entityName:
+          description: "Name of the entity (e.g. User, Product)"
+      required:
+        - entityName
+    messages:
+      - role: system
+        content: "You are a PHP code generator specializing in Symfony controllers."
+      - role: assistant
+        content: "I'll help you generate a controller for your entity. Please provide the entity name."
+      - role: user
+        content: "Generate a controller for the {{entityName}} entity."
+```
+
+Each prompt contains:
+
+- **id**: Unique identifier for the prompt
+- **description**: Human-readable description
+- **schema** (optional): Defines input parameters with descriptions and required fields
+- **messages**: The sequence of conversation messages that make up the prompt
+
+## Variable Substitution
+
+Prompts support variable substitution in message content using the format `{{variableName}}`. When LLM requests a
+prompt with arguments, the MCP server replaces these placeholders with the provided values.
+
+## Available Prompt Tools
+
+When connected via MCP, LLM has access to the following prompt-related tools:
+
+### Prompts Tools
+
+- `prompts.list`: List all available prompts defined in the configuration
+- `prompts.get`: Get a specific prompt by ID
+
+## Example Usage
+
+Here's how LLM might use prompts during a conversation:
+
+1. **Listing available prompts**:
+   Claude can request a list of all available prompts to discover what templates are available.
+
+2. **Using a prompt with arguments**:
+   Claude can request a specific prompt with arguments, which will return the prompt messages with variables
+   substituted.
+
+3. **Custom workflows**:
+   Prompts can be designed for specific workflows like code generation, documentation creation, or project analysis.
+
+## Shareable Prompts
+
+Prompts in Context Generator aren't just static templates - they're designed to be shared, imported, and reused across
+projects and teams. This creates an ecosystem where:
+
+- Teams can maintain consistent approaches to common development tasks
+- Best practices can be encoded once and shared widely
+- Specialized domain knowledge can be packaged into reusable templates
+- The community can collaborate on high-quality prompt libraries
+
+Context Generator currently supports basic configuration imports from local filesystem sources.
+
+**Coming soon**, we're extending this functionality to include remote sources, with a particular focus on making MCP
+prompts more accessible and shareable:
+
+### Upcoming Import Capabilities
+
+- **GitHub Repositories**: Import prompts directly from public or private GitHub repos
+- **Composer Packages**: Leverage prompts bundled in PHP Composer packages
+- **Remote URLs**: Reference prompt configurations via direct URLs
+- **Selective Imports**: Import only specific prompts from any source
+
+This will transform how teams work with AI by enabling:
+
+- **Reusability**: Create prompt repositories once, use them across multiple projects
+- **Community Sharing**: Participate in an ecosystem of community-maintained prompt libraries
+- **Standardization**: Promote best practices through shared prompt configurations
+- **Version Control**: Reference specific versions of remote prompt repositories
+
+### Example Remote Import Configuration
+
+```yaml
+import:
+  # Local import (current implementation)
+  - path: services/api/context.yaml
+    type: local # default, can be omitted
+
+  # GitHub import (coming soon)
+  - path: butschster/ctx-prompts/prompts/refactoring.yaml
+    type: github
+    ref: main # optional, defaults to main/master
+    token: ${GITHUB_TOKEN} # optional, for private repos
+
+  # Composer package import (coming soon)
+  - path: vendor/butschster/ctx-prompts/prompts/refactoring.yaml
+    type: composer
+
+  # URL import (coming soon)
+  - path: https://example.com/context-configs/api-prompts.yaml
+    type: url
+    headers: # optional HTTP headers
+      Authorization: "Bearer ${API_TOKEN}"
+
+  # Selective import (coming soon, works with any source type)
+  - path: butschster/ctx-prompts/prompts/all.yaml
+    type: github
+    docs:
+      - refactoring/extract-method.md
+      - refactoring/rename-class.md
+```

docs/quick-start.md

@@ -113,6 +113,23 @@ Point the MCP client to the Context Generator server:
 
 Now you can ask Claude questions about your codebase without manually uploading context files!
 
+## 7. Working with Prompts (Optional)
+
+Define prompts that can be used with MCP server.
+
+```yaml
+prompts:
+  - id: generate-controller
+    description: "Generate a controller for an entity"
+    messages:
+      - role: assistant
+        content: "I'll help you generate a controller."
+      - role: user
+        content: "Generate a controller for the {{entityName}} entity."
+```
+
+> **Note:** Read more about [Prompts](/mcp/prompts) for detailed configuration options.
+
 ## JSON Schema
 
 For better editing experience, Context Generator provides a JSON schema for autocompletion and validation in your IDE: