### Install Publishing Tools

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Installs the necessary command-line tools for publishing VS Code extensions.

```bash
npm install -g @vscode/vsce ovsx
```

--------------------------------

### Setup Working Directory

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Demonstrates the automatic setup of the '.superdesign' working directory within the project workspace, ensuring necessary directories exist for agent operations.

```typescript
private async setupWorkingDirectory(): Promise<void> {
    const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
    const superdesignDir = path.join(workspaceRoot, '.superdesign');
    
    if (!fs.existsSync(superdesignDir)) {
        fs.mkdirSync(superdesignDir, { recursive: true });
    }
    
    this.workingDirectory = superdesignDir;
}
```

--------------------------------

### Install Extension Locally for Testing

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Use this command to test a locally built .vsix file before publishing. Ensure you have Node.js 20+ installed.

```bash
code --install-extension file.vsix
```

--------------------------------

### Integrate Superdesign Commands

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Demonstrates how to call Superdesign extension commands from another extension. Includes examples for getting the current provider, sending a chat message, and opening the canvas.

```typescript
// Request current provider
vscode.commands.executeCommand('superdesign.getCurrentProvider')
    .then((result) => {
        console.log('Current model:', result.model);
    });

// Execute design prompt
await vscode.commands.executeCommand('superdesign.chatMessage', {
    message: 'Design a login form'
});

// Open canvas
vscode.commands.executeCommand('superdesign.openCanvas');
```

--------------------------------

### Example Workspace Configuration

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

This JSON snippet shows an example of how to configure the SuperDesign extension within a VS Code workspace's settings.json file. It sets the LLM provider, the path to the Claude code executable, and the AI model to be used.

```json
{
    "superdesign.llmProvider": "claude-code",
    "superdesign.claudeCodePath": "/opt/bin/claude",
    "superdesign.aiModel": "claude-3-5-sonnet-20241022"
}
```

--------------------------------

### Configuration Validation: Missing Binary

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Example error message when the Claude Code binary is not found, including installation instructions.

```text
Claude Code binary not found at 'claude'. 
Install: npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Basic Setup: Claude API

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Configure Superdesign for basic Claude API usage with an API key.

```json
{
    "superdesign.llmProvider": "claude-api",
    "superdesign.anthropicApiKey": "sk-ant-..."
}
```

--------------------------------

### Install Claude Code Binary

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Install the Claude Code binary globally using npm. This is required for certain Claude functionalities.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Verify Claude Code Installation

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Verify the installation of the Claude Code binary by checking its version. This command should be run after installation.

```bash
claude --version
```

--------------------------------

### Example settings.json Configuration

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Illustrates basic Superdesign settings within a VS Code settings.json file, including LLM provider, API key, and AI model.

```json
{
    "superdesign.llmProvider": "claude-api",
    "superdesign.anthropicApiKey": "sk-ant-…",
    "superdesign.aiModel": "claude-4-sonnet-20250514"
}
```

--------------------------------

### LLMProviderFactory.getInstance

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Gets or creates the singleton factory instance. This is the entry point for interacting with the factory.

```APIDOC
## LLMProviderFactory.getInstance

### Description
Gets or creates the singleton factory instance. This is the entry point for interacting with the factory.

### Method
Static method

### Parameters
#### Path Parameters
- **outputChannel** (vscode.OutputChannel) - Required - The output channel for logging.

### Returns
Singleton `LLMProviderFactory` instance.
```

--------------------------------

### Log Entry Format Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Illustrates the standard format for log entries, including timestamp, log level, and the message.

```log
[2024-01-15T10:30:45.123Z] [INFO] Superdesign extension activated!
[2024-01-15T10:30:46.456Z] [DEBUG] Canvas panel initialized
[2024-01-15T10:30:47.789Z] [ERROR] Failed to read file: ENOENT
```

--------------------------------

### Bash Tool Command Validation Examples

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Shows examples of dangerous patterns blocked by the bash tool to ensure security.

```typescript
// ✗ Blocked
rm -rf /
sudo su
format C:
chmod 777 /
```

--------------------------------

### Theme Tool Usage Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Demonstrates how to use the themeTool function with specific parameters to create a CSS theme file. Ensure all required CSS properties are included in the cssSheet.

```typescript
const result = await themeTool({
    theme_name: 'Dark Mode Professional',
    reasoning_reference: 'Reference: Vercel design system, used oklch for modern colors',
    cssSheet: ':root { --background: oklch(0.145 0 0); ... }',
    cssFilePath: '.superdesign/design_iterations/theme_1.css'
});
```

--------------------------------

### Local Claude Code Setup

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Configure Superdesign to use local Claude Code with a specified path and budget.

```json
{
    "superdesign.llmProvider": "claude-code",
    "superdesign.claudeCodePath": "claude",
    "superdesign.claudeCodeThinkingBudget": 100000
}
```

--------------------------------

### Configure LLM Provider to Claude Code CLI

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Sets the LLM provider to use the local 'claude-code' binary. This requires the 'claude' binary to be installed.

```json
{
    "superdesign.llmProvider": "claude-code"
}
```

--------------------------------

### Configuration Validation: Invalid Model

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Example error message for an unsupported model, showing fallback behavior.

```text
Model 'claude-invalid' is not supported. 
Falling back to default model.
```

--------------------------------

### Log Info Message Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Log an informational message. Optionally, display a notification in the status bar.

```typescript
Logger.info('Design file created: ui_1.html', true);
```

--------------------------------

### LLMProviderFactory.getProvider

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Gets or creates a provider of the specified type. It handles caching, initialization, and configuration reading.

```APIDOC
## LLMProviderFactory.getProvider

### Description
Gets or creates a provider of the specified type. It handles caching, initialization, and configuration reading.

### Method
Asynchronous instance method

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
- **providerType** (LLMProviderType) - Optional - Provider type to instantiate. Defaults to the value from `superdesign.llmProvider` configuration.

### Behavior
1. If `providerType` not provided, reads from `superdesign.llmProvider` config
2. Returns cached provider if already initialized
3. Creates and initializes new provider otherwise
4. Waits for initialization before returning

### Returns
Initialized `LLMProvider` instance ready for use.

### Request Example
```typescript
const provider = await factory.getProvider(LLMProviderType.CLAUDE_API);
const messages = await provider.query('Design a button');
```
```

--------------------------------

### Configure Claude Code CLI Path

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Set the path to the Claude Code CLI binary. Use this for non-standard installation paths or when using shell script installations.

```json
{
    "superdesign.claudeCodePath": "claude-code"
}
```

--------------------------------

### Workspace Boundary Enforcement Examples

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Illustrates allowed and blocked file paths for tools to prevent escaping the workspace and directory traversal.

```typescript
// ✓ Allowed
.superdesign/design_iterations/ui_1.html
src/components/Button.tsx

// ✗ Blocked (directory traversal)
../../secrets.json
/../../../etc/passwd

// ✗ Blocked (outside workspace)
/etc/passwd
C:\Windows\System32
```

--------------------------------

### Configuration Validation: Missing API Key

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Example error message indicating a missing API key for Anthropic.

```text
Anthropic API key not configured. 
Please run "Superdesign: Configure Anthropic API Key" command.
```

--------------------------------

### Log Warning Message Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Log a warning message. Optionally, display a notification in the status bar.

```typescript
Logger.warn('API key expires in 7 days');
```

--------------------------------

### Extension Activation

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

The `activate` function is the entry point for the Superdesign extension, responsible for its initialization and setup when VS Code activates the extension.

```APIDOC
## activate

### Description
Initializes the Superdesign extension when activated. This function sets up core services, registers commands, and configures UI components.

### Parameters
- **context** (`vscode.ExtensionContext`) - The extension context provided by VS Code, containing information and services for extension management.

### Functionality
- Initializes the centralized logger service.
- Creates a CustomAgentService instance.
- Registers all extension commands.
- Sets up WebView providers for the sidebar and canvas.
- Configures message handlers for inter-component communication.

### Activation Events
- `onCommand:superdesign.helloWorld`
- `onView:superdesign.chatView`
```

--------------------------------

### LLMProviderFactory.getProviderStatus

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Gets the status of all providers, including the current provider and the status of each available provider (ready, error, not_configured).

```APIDOC
## LLMProviderFactory.getProviderStatus

### Description
Gets the status of all providers, including the current provider and the status of each available provider (ready, error, not_configured).

### Method
Asynchronous instance method

### Returns
A `ProviderStatus` object:
- **current**: `LLMProviderType` - The currently active provider type.
- **providers**: `Array` of objects, each containing:
    - **type**: `LLMProviderType` - The provider type.
    - **name**: `string` - The display name of the provider.
    - **status**: `'ready' | 'error' | 'not_configured'` - The current status of the provider.
    - **error**: `string` (optional) - An error message if the status is 'error'.

### Usage:
Display provider selection UI with status indicators.
```

--------------------------------

### Access Output Channel Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Retrieve the VS Code output channel used by the logger for direct manipulation. This allows for custom log entries.

```typescript
const channel = Logger.getOutputChannel();
channel.appendLine('Custom log entry');
```

--------------------------------

### API Key Authentication Error Handling

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Provides an example of how to detect and handle API key authentication errors, triggering a user prompt to reconfigure the API key.

```typescript
if (provider.isAuthError(error.message)) {
    // Prompt user to reconfigure
    vscode.commands.executeCommand('superdesign.configureApiKey');
}
```

--------------------------------

### Data Flow: User Input to Agent Processing

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Details the initial steps of the data flow, starting from user input in the webview, its routing through the extension, and the initiation of agent processing.

```plaintext
Webview sends: { command: 'chatMessage', message: '...' }
↓
ChatSidebarProvider receives and routes
↓
ChatMessageService.handleChatMessage()
```

--------------------------------

### Set Log Level Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Configure the minimum severity level for log messages. Use LogLevel.DEBUG to capture all messages or LogLevel.WARN to only capture warnings and errors.

```typescript
Logger.setLevel(LogLevel.DEBUG);  // Log everything
Logger.setLevel(LogLevel.WARN);   // Only warnings and errors
```

--------------------------------

### Build and Publish Extension (All-in-One)

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

A single command to perform the build, VS Code Marketplace publish, and Open VSX Registry publish steps sequentially.

```bash
npm run package && \
npx vsce publish --pat YOUR_VSCE_TOKEN && \
npx ovsx publish -p YOUR_OVSX_TOKEN
```

--------------------------------

### Build and Publish Extension

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Commands to build the extension, publish to VS Code Marketplace, and publish to Open VSX Registry.

```bash
# Build the extension
npm run package

# Publish to VS Code Marketplace
npx vsce publish --pat YOUR_VSCE_TOKEN

# Publish to Open VSX Registry
npx ovsx publish -p YOUR_OVSX_TOKEN
```

--------------------------------

### Switch LLM Providers at Runtime

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Demonstrates how to switch between different LLM providers at runtime using a factory pattern and verifies the change.

```typescript
const factory = LLMProviderFactory.getInstance(outputChannel);

// Switch to Claude Code
const provider = await factory.switchProvider(
    LLMProviderType.CLAUDE_CODE
);

// Verify new provider
const status = await factory.getProviderStatus();
console.log('Current provider:', status.current);
```

--------------------------------

### Initialize ChatSidebarProvider

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Constructor for ChatSidebarProvider, requiring extension URI, agent service, and output channel.

```typescript
export class ChatSidebarProvider implements vscode.WebviewViewProvider {
    constructor(
        private readonly _extensionUri: vscode.Uri,
        private readonly agentService: AgentService,
        private readonly outputChannel: vscode.OutputChannel
    )
}
```

--------------------------------

### Project Initialization

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Commands related to setting up and initializing a Superdesign project within the workspace.

```APIDOC
## superdesign.initializeProject

### Description
Initializes the necessary project structure and configuration files for Superdesign within the current workspace.

### Usage
```typescript
async function initializeSuperdesignProject()
```

### Creates
- `.superdesign/design_iterations/` directory for design files.
- `default_ui_darkmode.css` with baseline design system styles.
- `.cursor/rules/design.mdc` for Cursor integration.
- `CLAUDE.md` with design rules for Claude Code.
- `.windsurfrules` for Windsurf integration.

### Behavior
- Checks if a workspace folder is open.
- Recursively creates directories with error handling.
- Appends rules to existing files or creates new ones if they don't exist.
- Notifies the user of success or failure.
```

--------------------------------

### createThemeTool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/API-SURFACE.md

Creates CSS theme files for a design system. Requires theme name, reasoning reference, CSS sheet, and file path.

```APIDOC
## createThemeTool

### Description
Creates CSS theme files for design system.

### Method
`createThemeTool(context: ExecutionContext): Tool`

### Parameters
- **theme_name** (string) - Required - The name of the theme.
- **reasoning_reference** (string) - Required - A reference for the theme's reasoning.
- **cssSheet** (string) - Required - The CSS content for the theme.
- **cssFilePath** (string) - Required - The path where the CSS file will be created.
- **create_dirs** (boolean) - Optional - Whether to create parent directories if they don't exist.
```

--------------------------------

### Configuration Reference

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/MANIFEST.md

Details all configuration settings, including LLM provider options, API keys, model selection, and advanced behaviors. Useful for end-users and DevOps.

```markdown
- Settings overview
  - Access methods (UI, commands, files)
  - Example settings.json
- LLM Provider settings
  - `superdesign.llmProvider` enum values
  - Configuration effects
- API Key configuration (3 keys)
  - Anthropic (`anthropicApiKey`)
  - OpenAI (`openaiApiKey`)
  - OpenRouter (`openrouterApiKey`)
  - Configuration methods, validation, obtaining keys
- Model selection (2 settings)
  - `superdesign.aiModel` with supported models
  - `superdesign.claudeCodeModelId` enum
  - `superdesign.aiModelProvider` options
  - Auto-detection logic
- Advanced options (4 settings)
  - Custom Anthropic URL
  - Custom OpenAI endpoint
  - Claude Code binary path
  - Thinking budget tokens
- Extension behavior settings
  - UI and display configuration
  - Available commands (12 listed)
- Configuration scopes (3 levels)
  - User, workspace, workspace folder
  - Priority order
  - Example workspace config
- Environment variables
  - Standard LLM env vars
  - Priority order
- Validation feedback
  - Error messages with solutions
- Common scenarios (5 examples)
  - Basic setup
  - Local Claude Code
  - OpenAI with custom endpoint
  - OpenRouter multi-model
  - Local development
- Troubleshooting section
  - API key issues
  - Provider initialization
  - Model selection
  - Binary not found
```

--------------------------------

### Full Extension Module Dependencies

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Specifies the main entry point and the inclusion of all providers, services, tools, and UI components for the complete extension.

```plaintext
src/extension.ts
→ All providers, services, tools
→ UI components (React)
```

--------------------------------

### CustomAgentService Constructor

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Initializes the CustomAgentService, setting up the working directory, logging, and detecting the workspace root.

```APIDOC
## constructor(outputChannel: vscode.OutputChannel)

### Description
Initializes the CustomAgentService.

### Parameters
- **outputChannel** (vscode.OutputChannel) - The output channel for logging.
```

--------------------------------

### Log Debug Message Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Log a message at the DEBUG level. Optionally, display a notification in the status bar.

```typescript
Logger.debug('Canvas panel initialized');
```

--------------------------------

### Dual Publishing Workflow Steps

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Execute these steps to publish updates to both SuperdesignDev and iganbold publishers, including versioning, committing, tagging, and reverting.

```bash
# 1. Publish to NEW publisher first (SuperdesignDev)
# - Update package.json version (e.g., 0.0.14)
npm run package && \
  npx vsce publish --pat YOUR_VSCE_TOKEN && \
  npx ovsx publish -p YOUR_OVSX_TOKEN

# 2. Prepare OLD publisher (iganbold)
# - Update to iganbold publisher
# - Change displayName to include (DEPRECATED)
# - Swap README with deprecation notice
# - Set version (e.g., 0.0.13)

# 3. Commit and tag for GitHub Actions
git add -A
git commit -m "Update deprecation version 0.0.X for iganbold publisher"
git tag v0.0.X
git push origin main && git push origin v0.0.X

# 4. Wait for GitHub Actions to complete
# Check: https://github.com/superdesigndev/superdesign/actions

# 5. Revert to SuperdesignDev
# - Restore README
# - Update package.json back to SuperdesignDev
# - Update extension.ts
git add -A
git commit -m "Revert to SuperdesignDev publisher for ongoing development"
git push origin main
```

--------------------------------

### LLMProviderFactory Singleton

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/API-SURFACE.md

The LLMProviderFactory is a singleton responsible for managing LLM providers. Use getInstance to get the factory instance.

```APIDOC
## LLMProviderFactory

### Description
Factory for creating and managing providers.

### Static Methods
#### `getInstance(outputChannel: vscode.OutputChannel): LLMProviderFactory`
Gets the singleton instance of the LLMProviderFactory.

### Instance Methods
#### `async getProvider(providerType?: LLMProviderType): Promise<LLMProvider>`
Retrieves an LLM provider based on the specified type.

#### `getCurrentProvider(): LLMProvider | null`
Gets the currently active LLM provider.

#### `async refreshCurrentProvider(): Promise<boolean>`
Refreshes the current LLM provider.

#### `async switchProvider(providerType: LLMProviderType): Promise<LLMProvider>`
Switches the current LLM provider to a new type.

#### `getAvailableProviders(): {type: LLMProviderType; name: string; description: string}[]`
Returns a list of all available LLM providers.

#### `async validateProvider(providerType: LLMProviderType): Promise<{isValid: boolean; error?: string}>`
Validates a specific LLM provider.

#### `async getProviderStatus(): Promise<ProviderStatus>`
Gets the status of the current LLM provider.

#### `dispose(): void`
Disposes of the LLMProviderFactory and its resources.
```

--------------------------------

### createBashTool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/API-SURFACE.md

Executes shell commands. Supports specifying a description, working directory, timeout, output capturing, and environment variables.

```APIDOC
## createBashTool

### Description
Executes shell commands.

### Method
`createBashTool(context: ExecutionContext): Tool`

### Parameters
- **command** (string) - Required - The shell command to execute.
- **description** (string) - Optional - A description of the command.
- **directory** (string) - Optional - The working directory for the command.
- **timeout** (number) - Optional - The timeout in milliseconds for the command.
- **capture_output** (boolean) - Optional - Whether to capture the command's output.
- **env** (object) - Optional - Environment variables for the command.
```

--------------------------------

### LLMStreamCallback Type and Usage

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Defines the callback function signature for streaming messages and provides an example of its usage with the query() method.

```typescript
type LLMStreamCallback = (message: LLMMessage) => void;

await provider.query(prompt, options, undefined, (message) => {
    console.log('Streamed message:', message);
    updateUI(message);
});
```

--------------------------------

### Extension Activation Function

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

The main entry point for the VS Code extension. It initializes core services, registers all commands, and sets up webview providers.

```typescript
export function activate(context: vscode.ExtensionContext)
```

--------------------------------

### Log Error Message Example

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Log an error message. A notification is shown by default for user visibility. Optionally, explicitly show a notification.

```typescript
Logger.error('Failed to save design', true);
```

--------------------------------

### createThemeTool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Creates CSS theme files for a design system. It takes a context and theme configuration to generate a CSS file with specified theme properties.

```APIDOC
## createThemeTool

### Description
Creates CSS theme files for a design system. It takes a context and theme configuration to generate a CSS file with specified theme properties.

### Function Signature
```typescript
export function createThemeTool(context: ExecutionContext): Tool
```

### Parameters
#### Function Parameters
- **theme_name** (string) - Required - Human-readable theme name
- **reasoning_reference** (string) - Required - Design decisions and references
- **cssSheet** (string) - Required - Full CSS content
- **cssFilePath** (string) - Required - Path to write CSS file
- **create_dirs** (boolean) - Optional - Create parent directories (default: true)

### Required CSS Properties
The `cssSheet` must include `:root` selector with:
- `--background`, `--foreground` (base colors)
- `--primary`, `--primary-foreground` (brand)
- `--secondary`, `--muted`, `--accent`
- `--destructive`, `--border`, `--input`, `--ring`
- `--card`, `--popover` + foreground variants
- `--chart-1` through `--chart-5`
- `--sidebar-*` variants
- `--font-sans`, `--font-serif`, `--font-mono`
- `--radius`, `--spacing`
- `--shadow-*` variants

### Returns
```typescript
{
    success: true;
    message: string;
    filePath: string;
    theme_name: string;
    reasoning_reference: string;
    cssSheet: string;
}
```

### Example
```typescript
const result = await themeTool({
    theme_name: 'Dark Mode Professional',
    reasoning_reference: 'Reference: Vercel design system, used oklch for modern colors',
    cssSheet: ':root { --background: oklch(0.145 0 0); ... }',
    cssFilePath: '.superdesign/design_iterations/theme_1.css'
});
```
```

--------------------------------

### Blocked Dangerous Commands

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Shows examples of bash commands that are blocked by the tool to prevent security risks such as data deletion or unauthorized access.

```typescript
// ✗ Blocked
rm -rf /
sudo su
format C:
```

--------------------------------

### Get Working Directory

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Retrieves the current working directory used by the ClaudeCodeService for file operations. This is typically the absolute path to the workspace directory.

```typescript
getWorkingDirectory(): string
```

--------------------------------

### Register Hello World Command

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Registers the 'superdesign.helloWorld' command to display an information message. This is useful for testing extension activation.

```typescript
vscode.commands.registerCommand('superdesign.helloWorld', () => {
    vscode.window.showInformationMessage('Hello World from superdesign!');
});
```

--------------------------------

### API Surface Quick Reference

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/MANIFEST.md

A quick reference for all exported APIs, including commands, entry points, services, providers, tools, and types. Aids in API discovery and skimming.

```markdown
- Extension commands table (13 entries)
- Extension entry points
  - `activate()`, `deactivate()`
- Services summary (4 services)
  - Signatures and method lists
- LLM providers (3 total)
  - Abstract base + 2 implementations
- WebView providers (2 total)
- Tools reference (9 tools)
  - Export signatures
  - Quick parameter summaries
- Tool utilities (7 functions)
- Types and interfaces (20+)
  - Organized by category
- Configuration settings table (10 entries)
- Message protocol summary
  - 15+ message types organized
- Summary statistics
  - Count of each component type
  - Total documentation lines
- Files generated list
```

--------------------------------

### Activate and Integrate Extension Services

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

This snippet shows the main activation logic for a VS Code extension. It initializes services, sets up a webview provider, and registers message handlers for inter-service communication.

```typescript
// In extension.ts
import { Logger } from './services/logger';
import { CustomAgentService } from './services/customAgentService';
import { ChatMessageService } from './services/chatMessageService';

export function activate(context: vscode.ExtensionContext) {
    // Initialize logger
    Logger.initialize();
    Logger.info('Superdesign extension activated');
    
    // Create agent service
    const customAgent = new CustomAgentService(Logger.getOutputChannel());
    
    // Create chat message service
    const messageService = new ChatMessageService(
        customAgent,
        Logger.getOutputChannel()
    );
    
    // Create sidebar provider
    const sidebarProvider = new ChatSidebarProvider(
        context.extensionUri,
        customAgent,
        Logger.getOutputChannel()
    );
    
    // Register webview view provider
    vscode.window.registerWebviewViewProvider(
        ChatSidebarProvider.VIEW_TYPE,
        sidebarProvider
    );
    
    // Subscribe to messages
    sidebarProvider.setMessageHandler(async (message) => {
        switch (message.command) {
            case 'chatMessage':
                await messageService.handleChatMessage(message, sidebarProvider._view?.webview);
                break;
            case 'stopChat':
                await messageService.stopCurrentChat(sidebarProvider._view?.webview);
                break;
        }
    });
}

export function deactivate() {
    Logger.dispose();
}
```

--------------------------------

### Get Provider Information

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Retrieves information about the currently configured LLM provider. Includes the provider's name and type (e.g., 'api' or 'binary').

```typescript
async getProviderInfo(): Promise<ProviderInfo>
```

--------------------------------

### Resolve Workspace Path

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Converts relative or absolute file paths into absolute paths within the workspace. Example shows resolving 'src/file.ts' to an absolute path.

```typescript
export function resolveWorkspacePath(
    filePath: string,
    context: ExecutionContext
): string
```

```typescript
const absolute = resolveWorkspacePath('src/file.ts', context);
// Returns: /workspace/project/.superdesign/src/file.ts
```

--------------------------------

### createBashTool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Executes shell commands. It includes safety features like blocking dangerous patterns, validating directory paths, and implementing timeouts.

```APIDOC
## createBashTool

### Description
Executes shell commands. It includes safety features like blocking dangerous patterns, validating directory paths, and implementing timeouts.

### Method
`createBashTool(context: ExecutionContext)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **command** (string) - Yes - Shell command to execute
- **description** (string) - No - Command description for logging
- **directory** (string) - No - Working directory (relative to workspace)
- **timeout** (number) - No - Timeout in ms (default: 30000)
- **capture_output** (boolean) - No - Capture stdout/stderr (default: true)
- **env** (Object) - No - Environment variables

### Request Example
```typescript
const result = await bashTool({
    command: 'npm install',
    directory: '.',
    timeout: 60000
});
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the command executed successfully.
- **command** (string) - The executed shell command.
- **directory** (string) - The working directory where the command was executed.
- **stdout** (string) - The standard output of the command.
- **stderr** (string) - The standard error of the command.
- **exitCode** (number | null) - The exit code of the command, or null if terminated by a signal.
- **signal** (string | null) - The signal that terminated the process, if any.
- **duration** (number) - The execution time in milliseconds.
- **timedOut** (boolean) - Indicates if the command timed out.

#### Response Example
```json
{
  "success": true,
  "command": "npm install",
  "directory": ".",
  "stdout": "...",
  "stderr": "",
  "exitCode": 0,
  "signal": null,
  "duration": 1500,
  "timedOut": false
}
```
```

--------------------------------

### createLsTool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/API-SURFACE.md

Lists directory contents. Supports recursive listing, including hidden files, and long format output.

```APIDOC
## createLsTool

### Description
Lists directory contents.

### Method
`createLsTool(context: ExecutionContext): Tool`

### Parameters
- **path** (string) - Optional - The path of the directory to list.
- **recursive** (boolean) - Optional - Whether to list recursively.
- **include_hidden** (boolean) - Optional - Whether to include hidden files.
- **long_format** (boolean) - Optional - Whether to use long format output.
```

--------------------------------

### Get All Provider Statuses

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Fetches the status of all available LLM providers. This includes the current provider and a list of other providers with their respective statuses (ready, error, not_configured).

```typescript
async getProviderStatus(): Promise<ProviderStatus>
```

--------------------------------

### Create Tool with AI SDK

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

A standard pattern for creating tools using Vercel's AI SDK. It includes defining tool parameters with Zod and handling execution logic with error management.

```typescript
import { tool } from 'ai';
import { z } from 'zod';

export function createXyzTool(context: ExecutionContext) {
    return tool({
        description: 'Human-readable description',
        parameters: z.object({
            param1: z.string().describe('Parameter description'),
            param2: z.number().optional().describe('Optional param')
        }),
        execute: async ({ param1, param2 }): Promise<ToolResponse> => {
            try {
                // Tool logic here
                return {
                    success: true,
                    result: 'output'
                };
            } catch (error) {
                return handleToolError(error, 'Tool name', 'execution');
            }
        }
    });
}
```

--------------------------------

### LLMProviderFactory.getAvailableProviders

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Lists all available provider options, including their type, name, and description.

```APIDOC
## LLMProviderFactory.getAvailableProviders

### Description
Lists all available provider options, including their type, name, and description.

### Method
Instance method

### Returns
An array of `ProviderInfo` objects, each containing:
- **type**: `LLMProviderType` - The type identifier for the provider.
- **name**: `string` - The display name of the provider.
- **description**: `string` - A brief description of the provider.

### Example:
```typescript
[
    {
        type: LLMProviderType.CLAUDE_API,
        name: 'Claude API',
        description: 'Uses Anthropic API key to communicate with Claude via SDK'
    },
    {
        type: LLMProviderType.CLAUDE_CODE,
        name: 'Claude Code Binary',
        description: 'Uses local claude-code binary for enhanced code execution capabilities'
    }
]
```
```

--------------------------------

### Minimal Core Module Dependencies

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Lists the essential TypeScript files required for agent SDK integration. Highlights that CustomAgentService can be used independently.

```plaintext
src/types/agent.ts
src/providers/llmProvider.ts
src/providers/llmProviderFactory.ts
→ CustomAgentService can be used standalone
```

--------------------------------

### Extension Activation Lifecycle

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Outlines the sequence of events when the extension is activated. This includes initialization of core services and registration of commands and providers.

```plaintext
1. Extension loads
2. activate() called
3. Logger initialized
4. CustomAgentService created
5. Commands registered
6. WebView providers registered
7. Ready for user interaction
```

--------------------------------

### Get Singleton LLMProviderFactory Instance

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Retrieves the singleton instance of the LLMProviderFactory. This is typically the first step before interacting with other factory methods. Ensure a logger output channel is available.

```typescript
const factory = LLMProviderFactory.getInstance(Logger.getOutputChannel());
```

--------------------------------

### File Organization: Source Directory Structure

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Provides a detailed breakdown of the 'src' directory, showing the location of key files and subdirectories for extension entry points, providers, services, tools, types, templates, and the webview.

```plaintext
src/
├── extension.ts                 # Main entry point
├── providers/
│   ├── llmProvider.ts          # Abstract base
│   ├── llmProviderFactory.ts   # Factory pattern
│   ├── claudeApiProvider.ts    # Claude API impl
│   ├── claudeCodeProvider.ts   # Claude Code impl
│   ├── chatSidebarProvider.ts  # Webview provider
│   └── ...other providers
│
├── services/
│   ├── customAgentService.ts   # AgentService impl
│   ├── chatMessageService.ts   # Chat logic
│   ├── claudeCodeService.ts    # Claude Code mgmt
│   └── logger.ts               # Logging
│
├── tools/
│   ├── read-tool.ts
│   ├── write-tool.ts
│   ├── edit-tool.ts
│   ├── bash-tool.ts
│   ├── glob-tool.ts
│   ├── grep-tool.ts
│   ├── ls-tool.ts
│   ├── theme-tool.ts
│   ├── multiedit-tool.ts
│   ├── tool-utils.ts           # Shared utilities
│   └── ...
│
├── types/
│   ├── agent.ts
│   ├── context.ts
│   └── ...
│
├── templates/
│   └── webviewTemplate.ts
│
└── webview/                    # React components
    ├── App.tsx
    ├── components/
    │   ├── Chat/
    │   ├── Canvas/
    │   └── ...
    └── ...
```

--------------------------------

### Get Available LLM Providers

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Retrieves a list of all available LLM provider options, including their type, name, and description. This is useful for populating UI elements for provider selection.

```typescript
[
    {
        type: LLMProviderType.CLAUDE_API,
        name: 'Claude API',
        description: 'Uses Anthropic API key to communicate with Claude via SDK'
    },
    {
        type: LLMProviderType.CLAUDE_CODE,
        name: 'Claude Code Binary',
        description: 'Uses local claude-code binary for enhanced code execution capabilities'
    }
]
```

--------------------------------

### Configure OpenRouter API Key

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Executes the command to set up the OpenRouter API key for accessing models.

```typescript
await configureOpenRouterApiKey();
```

--------------------------------

### Configure Anthropic API Key in Settings

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Set the Anthropic API key directly in your VS Code settings. This key is required for the Claude API provider and must start with 'sk-ant-'.

```json
{
    "superdesign.anthropicApiKey": "sk-ant-v1234567890abcdef"
}
```

--------------------------------

### Write Tool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/agent-and-tools.md

Creates or overwrites files with specified content and encoding. Supports creating parent directories.

```APIDOC
## Write Tool

### Description
Creates or overwrites files with specified content. Supports creating parent directories and custom file encoding.

### Function Signature
```typescript
createWriteTool(context: ExecutionContext): Tool
```

### Parameters
#### Path Parameters
- **filePath** (string) - Required - File path (relative to workspace)
- **content** (string) - Required - File content to write
- **create_dirs** (boolean) - Optional - Create parent dirs (default: true)
- **encoding** (string) - Optional - File encoding (default: 'utf8')
- **overwrite** (boolean) - Optional - Overwrite existing file (default: true)

### Returns
```typescript
{
    success: true;
    filePath: string;
    bytesWritten: number;
    isNewFile: boolean;
}
```

### Example
```typescript
const result = await writeTool({
    filePath: '.superdesign/design_iterations/ui_1.html',
    content: '<html>...</html>'
});
```
```

--------------------------------

### Define Initialize Context Command

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/types.md

Extends the base WebviewMessage to define a command for initializing the webview's context when it first loads. It uses the 'initContext' command type and carries the WebviewContext object.

```typescript
export interface InitContext extends WebviewMessage {
    command: 'initContext';
    context: WebviewContext;
}
```

--------------------------------

### Configure OpenAI API Key in Settings

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Set your OpenAI API key in VS Code settings. This key is required for the custom agent when using the OpenAI provider and must start with 'sk-'.

```json
{
    "superdesign.openaiApiKey": "sk-proj-..."
}
```

--------------------------------

### Configure Custom OpenAI URL

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Executes the command to configure a custom OpenAI-compatible API endpoint, such as for local development with LM Studio. The URL must start with 'http://' or 'https://'.

```typescript
await configureOpenAIUrl();
```

--------------------------------

### Set OpenRouter API Key Environment Variable

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Set the OPENROUTER_API_KEY environment variable for authentication with OpenRouter.

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

--------------------------------

### Create Deprecation README

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Replace the existing README.md with a deprecation notice, directing users to the new official extension.

```bash
# Save your current README
mv README.md README_ORIGINAL.md

# Create deprecation README
cat > README.md << 'EOF'
# ⚠️ THIS EXTENSION HAS BEEN DEPRECATED

## 🚨 Important Notice

This extension has moved to a new publisher account. Please uninstall this version and install the new official version:

### 👉 **[Install the New Official Extension](https://marketplace.visualstudio.com/items?itemName=SuperdesignDev.superdesign-official)**

[... rest of deprecation message ...]
EOF
```

--------------------------------

### Get LLM Provider Status

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Retrieves the status of all configured LLM providers, including the currently active one and the readiness state of others. This information is typically used to display status indicators in a UI.

```typescript
{
    current: LLMProviderType;
    providers: Array<{ 
        type: LLMProviderType;
        name: string;
        status: 'ready' | 'error' | 'not_configured';
        error?: string;
    }>;
}
```

--------------------------------

### Get and Query LLM Provider

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Obtains an initialized LLM provider for a specific type and sends a query to it. The provider is cached if already created. If no provider type is specified, it defaults to the one configured in `superdesign.llmProvider`.

```typescript
const provider = await factory.getProvider(LLMProviderType.CLAUDE_API);
const messages = await provider.query('Design a button');
```

--------------------------------

### Publish Regular Update to SuperdesignDev

Source: https://github.com/superdesigndev/superdesign/blob/main/deploy_note.md

Use this command to update the version in package.json, publish to the SuperdesignDev publisher, and then publish to Open VSX.

```bash
# Edit package.json version
npm run package && \
npx vsce publish --pat YOUR_TOKEN && \
npx ovsx publish -p YOUR_OVSX_TOKEN
```

--------------------------------

### Resolve Webview View for Chat

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Sets up the webview for the chat sidebar, including HTML template and message handlers. This method is part of the vscode.WebviewViewProvider interface.

```typescript
resolveWebviewView(
    webviewView: vscode.WebviewView,
    _context: vscode.WebviewViewResolveContext,
    _token: vscode.CancellationToken
): void
```

--------------------------------

### Define and Create a Superdesign Tool

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

This snippet shows how to define a tool's schema using Zod and create the tool using the Vercel SDK. It includes parameter validation and error handling within the execute function.

```typescript
// 1. Define schema using Zod
const schema = z.object({
    param: z.string().describe('Description')
});

// 2. Create tool using Vercel SDK
export function createXyzTool(context: ExecutionContext) {
    return tool({
        description: 'What this tool does',
        parameters: schema,
        execute: async (args) => {
            // Validate paths
            const validationError = validateWorkspacePath(args.path, context);
            if (validationError) return validationError;
            
            try {
                // Do work
                return createSuccessResponse({ result: '...' });
            } catch (error) {
                return handleToolError(error, 'Context', 'execution');
            }
        }
    });
}
```

--------------------------------

### ChatMessageService Constructor

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Initializes the ChatMessageService. Requires an AgentService for chat logic and a vscode.OutputChannel for logging.

```typescript
constructor(
    agentService: AgentService,
    outputChannel: vscode.OutputChannel
)
```

--------------------------------

### Configure AI Model Provider in Settings

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/configuration.md

Select the AI model provider for the custom agent service. Note that `superdesign.llmProvider` is preferred for the main LLM provider.

```json
{
    "superdesign.aiModelProvider": "openrouter"
}
```

--------------------------------

### Execute Open Settings Command

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Executes the VS Code command to open the settings UI, filtered to show settings for the Superdesign extension.

```typescript
vscode.commands.executeCommand('workbench.action.openSettings', '@ext:SuperdesignDev.superdesign-official');
```

--------------------------------

### LLMProviderFactory.switchProvider

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/llm-providers.md

Switches to a different provider type, updating configuration, validating, initializing, and setting it as the current provider.

```APIDOC
## LLMProviderFactory.switchProvider

### Description
Switches to a different provider type, updating configuration, validating, initializing, and setting it as the current provider.

### Method
Asynchronous instance method

### Parameters
#### Path Parameters
- **providerType** (LLMProviderType) - Required - The new provider type to switch to.

### Behavior
1. Updates `superdesign.llmProvider` configuration
2. Validates new provider
3. Initializes provider
4. Sets as current provider

### Returns
Initialized `LLMProvider` of the new type.

### Example:
```typescript
await factory.switchProvider(LLMProviderType.CLAUDE_CODE);
```
```

--------------------------------

### Allowed and Blocked File Paths

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/README.md

Illustrates file paths that are permitted within the workspace boundaries and those that are blocked due to directory traversal or attempts to access outside the workspace.

```typescript
// ✓ Allowed
.superdesign/design_iterations/ui.html
src/components/button.tsx

// ✗ Blocked
../../secrets.json      // Directory traversal
/etc/passwd            // Outside workspace
../../../root/.ssh     // Parent directory escape
```

--------------------------------

### isReady

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Checks if the Claude Code service is ready to process queries.

```APIDOC
## isReady

### Description
Checks if the service is ready for queries. This indicates whether the provider is initialized and ready to accept requests.

### Method
`get isReady(): boolean`

### Returns
`true` if provider is initialized and ready.
```

--------------------------------

### Initialize Superdesign Project Function Signature

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/extension.md

Provides the function signature for initializing the Superdesign project structure within the workspace. This function handles the creation of directories and configuration files.

```typescript
async function initializeSuperdesignProject()
```

--------------------------------

### ClaudeCodeService Constructor

Source: https://github.com/superdesigndev/superdesign/blob/main/_autodocs/api-reference/services.md

Initializes the ClaudeCodeService with a VS Code output channel for logging.

```APIDOC
## ClaudeCodeService Constructor

### Description
Initializes the ClaudeCodeService with a VS Code output channel for logging.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```typescript
constructor(outputChannel: vscode.OutputChannel)
```

#### Parameters
- **outputChannel** (vscode.OutputChannel) - Required - VS Code output channel for logging
```