### Install VibeCoding Logger

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Instructions for installing the VibeCoding Logger library using package managers for Python and TypeScript/Node.js environments. This is the first step to integrate the logger into your project.

```bash
pip install vibelogger
```

```bash
npm install vibelogger
```

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

### Install VibeCoding Logger (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Instructions to install the VibeCoding Logger library using pip for Python projects.

```bash
pip install vibelogger
```

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

### VibeCoding Logger Environment Object Example

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Illustrative example of the 'environment' field, showing how runtime environment details can be included in a log entry for reproducibility and AI-driven debugging.

```JSON
{
    "language": "python",
    "language_version": "3.11.0",
    "os": "Darwin",
    "platform": "darwin-arm64",
    "hostname": "MacBook-Pro.local"
}
```

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

### Minimal VibeLogger API Usage Example

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Provides a basic example of how to initialize and use the VibeLogger API in TypeScript, demonstrating both simple logger creation and advanced configuration options for custom logging behavior.

```typescript
// Main logger creation
import { createFileLogger, createLogger, VibeLoggerConfig } from 'vibelogger';

// Simple usage (matches Python)
const logger = createFileLogger('my-project');

logger.info('user_login', 'User authentication started', {
  context: { userId: '123', method: 'oauth' },
  humanNote: 'Monitor for suspicious patterns',
  aiTodo: 'Check for anomalies in login time'
});

// Advanced usage
const config = new VibeLoggerConfig({
  logFile: './logs/custom.log',
  maxFileSizeMb: 50,
  autoSave: true
});

const customLogger = createLogger(config);
```

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

### Install VibeCoding Logger using npm

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This snippet shows how to install the VibeCoding Logger library using the npm package manager. It's the first step to integrate the logger into your Node.js or TypeScript project.

```bash
npm install vibelogger
```

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

### VibeCoding Logger Context Object Example

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Illustrative example of the 'context' field, demonstrating how structured data relevant to an operation can be embedded within a log entry for detailed AI analysis.

```JSON
{
    "user_id": "123",
    "source": "api_endpoint",
    "query_duration_ms": 45
}
```

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

### Example of AI-Optimized Structured Log Output

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

A JSON example showing the structured data format produced by the VibeCoding Logger, optimized for LLM consumption, including fields like timestamp, correlation_id, operation, context, environment, source, human_note, and ai_todo.

```json
{
  "timestamp": "2025-07-07T08:36:42.123Z",
  "level": "ERROR", 
  "correlation_id": "req_abc123",
  "operation": "fetchUserProfile",
  "message": "User profile not found",
  "context": {
    "user_id": "user-123",
    "query": "SELECT * FROM users WHERE id = ?"
  },
  "environment": {
    "python_version": "3.11.0",
    "os": "Darwin"
  },
  "source": "/app/user_service.py:42 in get_user_profile()",
  "human_note": "AI-TODO: Check database connection",
  "ai_todo": "Analyze why user lookup is failing"
}
```

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

### VibeLogger Usage: Contextual Logging and AI Integration

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/CONCEPT.md

This Python example demonstrates how to initialize VibeLogger, log informational messages with rich contextual data (including user details, IP, and AI-specific instructions), and handle exceptions by logging them with associated context. It also shows how to retrieve formatted logs specifically for AI analysis, highlighting the library's capability to provide structured data for machine learning and AI-driven insights.

```Python
from vibelogger import create_file_logger

# Create logger with auto-save to timestamped file
logger = create_file_logger("my_project")

# Log with rich context
logger.info(
    operation="user_login",
    message="User authentication started",
    context={
        "user_id": "123",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0..."
    },
    human_note="Monitor for suspicious login patterns",
    ai_todo="Check if multiple failed attempts from this IP"
)

# Log exceptions with full context
try:
    result = process_payment(order_id)
except Exception as e:
    logger.log_exception(
        operation="payment_processing",
        exception=e,
        context={"order_id": order_id, "amount": 99.99},
        ai_todo="Suggest error handling improvements"
    )

# Get logs formatted for AI analysis
ai_context = logger.get_logs_for_ai()
```

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

### Log File Organization Example

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Illustrates the automatic organization of log files by VibeCoding Logger. Logs are timestamped and stored within project-specific directories, with an example of a rotated log file indicating its original timestamp and rotation time.

```text
./logs/
├── my_project/
│   ├── vibe_20250707_143052.log
│   ├── vibe_20250707_151230.log
│   └── vibe_20250707_163045.log.20250707_170000  # Rotated
└── other_project/
    └── vibe_20250707_144521.log
```

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

### Basic Usage of VibeCoding Logger in TypeScript

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This example demonstrates how to initialize a file logger and perform basic logging operations. It covers logging information with rich context, human notes, and AI-specific tasks, as well as handling exceptions with detailed error logging.

```typescript
import { createFileLogger } from 'vibelogger';

// Create logger with auto-save to timestamped file
const logger = createFileLogger('my-project');

// Log with rich context for AI analysis
await logger.info('user_login', 'User authentication started', {
  context: {
    userId: '123',
    method: 'oauth',
    ipAddress: '192.168.1.100'
  },
  humanNote: 'Monitor for suspicious patterns',
  aiTodo: 'Check if multiple failed attempts from this IP'
});

// Log exceptions with full context
try {
  await riskyOperation();
} catch (error) {
  await logger.logException('payment_processing', error, {
    context: { orderId: 'order-123', amount: 99.99 },
    aiTodo: 'Suggest error handling improvements'
  });
}

// Get logs formatted for AI analysis
const aiContext = await logger.getLogsForAI();
console.log(aiContext); // Send this to your LLM
```

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

### Log File System Organization Example

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

Illustrates the automatic file organization structure for Vibe-Logger, where log files are stored under a 'logs' directory, categorized by project, and named with timestamps. It also shows an example of a rotated log file.

```text
./logs/
├── my-project/
│   ├── vibe_20250707_143052.log
│   ├── vibe_20250707_151230.log
│   └── vibe_20250707_163045.log.20250707_170000  # Rotated
└── other-project/
    └── vibe_20250707_144521.log
```

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

### Python Example: Thread-Safe Logging with VibeCoding Logger

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

This Python code demonstrates the thread-safety of the VibeCoding Logger. It shows how multiple threads can concurrently use a single logger instance to record messages without conflicts, ensuring reliable logging in multi-threaded applications.

```python
import threading
from vibelogger import create_file_logger

logger = create_file_logger("multi_threaded_app")

def worker(worker_id):
    logger.info(
        operation="worker_task",
        message=f"Worker {worker_id} processing",
        context={"worker_id": worker_id}
    )

# Safe to use across multiple threads
threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
```

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

### Example of AI-Understandable Structured Log Data (JSON)

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

This JSON snippet illustrates the structured log format produced by VibeCoding Logger. It includes essential fields like timestamp, correlation ID, operation, context, environment, and specific AI instructions, making logs directly consumable by Large Language Models for analysis.

```json
{
  "timestamp": "2025-07-07T08:36:42.123Z",
  "level": "ERROR", 
  "correlation_id": "req_abc123",
  "operation": "fetchUserProfile",
  "message": "User profile not found",
  "context": {
    "user_id": "user-123",
    "query": "SELECT * FROM users WHERE id = ?"
  },
  "environment": {
    "python_version": "3.11.0",
    "os": "Darwin"
  },
  "source": "/app/user_service.py:42 in get_user_profile()",
  "human_note": "AI-TODO: Check database connection",
  "ai_todo": "Analyze why user lookup is failing"
}
```

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

### VibeCoding Logger Thread Safety Example

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Demonstrates the thread-safe nature of VibeCoding Logger. This Python example shows how multiple threads can concurrently log messages using a shared logger instance without encountering race conditions or data corruption, ensuring reliable logging in multi-threaded applications.

```python
import threading
from vibelogger import create_file_logger

logger = create_file_logger("multi_threaded_app")

def worker(worker_id):
    logger.info(
        operation="worker_task",
        message=f"Worker {worker_id} processing",
        context={"worker_id": worker_id}
    )

# Safe to use across multiple threads
threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
```

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

### Configure VibeLogger using a Configuration Object

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This example demonstrates how to configure a VibeLogger instance by passing a `VibeLoggerConfig` object to the `createLogger` function. It covers settings like correlation ID, log file path, auto-save, file size limits, and in-memory log management.

```typescript
import { createLogger, type VibeLoggerConfig } from 'vibelogger';

const config: VibeLoggerConfig = {
  correlationId: 'custom-correlation-id',
  logFile: './logs/app.log',
  autoSave: true,
  maxFileSizeMb: 50,
  keepLogsInMemory: true,
  maxMemoryLogs: 1000,
  createDirs: true
};

const logger = createLogger(config);
```

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

### Configure VibeCoding Logger for Memory Efficiency (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Provides an example of configuring VibeCoding Logger for long-running processes where memory efficiency is critical. It demonstrates how to disable in-memory log storage to prevent out-of-memory issues, ensuring logs are written directly to disk.

```python
from vibelogger import VibeLoggerConfig, create_logger

# For long-running processes - disable memory storage
config = VibeLoggerConfig(
    log_file="./logs/production.log",
    keep_logs_in_memory=False,  # Don't store logs in memory
    auto_save=True
)
logger = create_logger(config=config)
```

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

### Advanced VibeLogger: Memory Management Configuration

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This example demonstrates how to configure VibeLogger for optimized memory usage, especially for long-running services. By disabling `keepLogsInMemory` and enabling `autoSave`, logs are written directly to files, reducing in-memory footprint.

```typescript
const logger = createLogger({
  keepLogsInMemory: false,  // Don't store in memory
  autoSave: true,          // Save directly to file
  maxFileSizeMb: 100       // Rotate at 100MB
});
```

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

### In-Memory Log Buffer and Concurrency Control

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Demonstrates how log entries are managed in an in-memory buffer, including appending new entries and evicting the oldest ones to maintain a maximum size. The Python example uses a lock for thread safety, while the TypeScript example uses an `async-mutex` for asynchronous concurrency control.

```python
with self._logs_lock:
    self.logs.append(entry)
    if len(self.logs) > max_logs:
        self.logs.pop(0)
```

```typescript
import { Mutex } from 'async-mutex';

class VibeLogger {
  private logs: LogEntry[] = [];
  private logsMutex = new Mutex();
  
  private async addToMemory(entry: LogEntry): Promise<void> {
    await this.logsMutex.runExclusive(() => {
      this.logs.push(entry);
      if (this.logs.length > this.config.maxMemoryLogs) {
        this.logs.shift(); // Remove first element
      }
    });
  }
}
```

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

### Advanced VibeLogger: Comprehensive Error Handling

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This example illustrates VibeLogger's robust error handling capabilities using `logException`. It demonstrates how the logger can gracefully handle various JavaScript error types, including `Error` objects, strings, custom objects, numbers, and null values.

```typescript
const errors = [
  new Error('Standard error'),
  'String error',
  { custom: 'object error' },
  42,
  null
];

for (const error of errors) {
  await logger.logException('error_handling', error);
}
```

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

### VibeCoding Logger Structured JSON Log Example

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/CONCEPT.md

This JSON snippet illustrates the structured format of a log entry generated by the VibeCoding Logger. It includes essential fields like timestamp, log level, correlation ID, operation name, a detailed message, contextual data (user ID, profile data, source), stack trace for errors, and dedicated fields for human annotations ('human_note') and AI-specific tasks ('ai_todo'). This structure is optimized for AI processing to provide comprehensive diagnostic information.

```JSON
{
  "timestamp": "2025-07-07T08:36:42.123Z",
  "level": "ERROR",
  "correlation_id": "req_abc123",
  "operation": "fetchUserProfile",
  "message": "Failed to extract name from user profile",
  "context": {
    "user_id": "user-12345",
    "profile_data": null,
    "source": "UserProfile.js:42"
  },
  "stack_trace": "TypeError: Cannot read properties of null...",
  "human_note": "AI-TODO: Check why findUserById returns null",
  "ai_todo": "Analyze database query logic"
}
```

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

### Example Structured JSON Log Format

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

Defines the standard JSON structure for logs, including fields for timestamp, log level, correlation ID, operation, message, contextual data, environment details, source, stack trace, human notes, and AI-specific directives. This format ensures compatibility across different language implementations.

```json
{
  "timestamp": "2025-07-07T10:30:45.123Z",
  "level": "ERROR",
  "correlation_id": "req-abc-123",
  "operation": "payment_processing",
  "message": "Payment gateway timeout",
  "context": {
    "orderId": "order-123",
    "amount": 99.99,
    "gateway": "stripe"
  },
  "environment": {
    "node_version": "v20.10.0",
    "os": "darwin",
    "platform": "Darwin",
    "architecture": "arm64",
    "runtime": "node"
  },
  "source": "payment.ts:42 in processPayment()",
  "stack_trace": "Error: Payment gateway timeout\n    at processPayment...",
  "human_note": "Payment timeouts have increased lately",
  "ai_todo": "Analyze payment gateway performance trends"
}
```

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

### Basic Logging with VibeCoding Logger (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Demonstrates how to create a file logger, log informational messages with context and human annotations, and handle exceptions with AI-specific instructions. Shows how to retrieve logs formatted for AI analysis.

```python
from vibelogger import create_file_logger

# Create logger with auto-save to timestamped file
logger = create_file_logger("my_project")

# Log with rich context for AI analysis
logger.info(
    operation="fetchUserProfile",
    message="Starting user profile fetch",
    context={"user_id": "123", "source": "api_endpoint"},
    human_note="AI-TODO: Check if user exists before fetching profile"
)

# Log exceptions with full context
try:
    result = risky_operation()
except Exception as e:
    logger.log_exception(
        operation="fetchUserProfile",
        exception=e,
        context={"user_id": "123"},
        ai_todo="Suggest proper error handling for this case"
    )

# Get logs formatted for AI analysis
ai_context = logger.get_logs_for_ai()
print(ai_context)  # Send this to your LLM for analysis
```

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

### Configure VibeCoding Logger via Environment Variables (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Shows how to initialize the logger using environment variables for configuration, such as log file path, max file size, and auto-save settings.

```python
from vibelogger import create_env_logger

# Set environment variables:
# VIBE_LOG_FILE=/path/to/logfile.log
# VIBE_MAX_FILE_SIZE_MB=25
# VIBE_AUTO_SAVE=true

logger = create_env_logger()
```

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

### Configure VibeCoding Logger via Environment Variables (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Shows how to initialize the VibeCoding Logger in Python by reading configuration settings directly from environment variables. This method allows for flexible deployment and configuration without modifying code.

```python
from vibelogger import create_env_logger

# Set environment variables:
# VIBE_LOG_FILE=/path/to/logfile.log
# VIBE_MAX_FILE_SIZE_MB=25
# VIBE_AUTO_SAVE=true

logger = create_env_logger()
```

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

### Project Build and Testing Bash Commands

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

Essential bash commands for managing the Vibe-Logger project lifecycle, including building the TypeScript source, running unit tests, enabling continuous testing with watch mode, and performing static analysis for type checking and linting.

```bash
# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type checking
npm run lint
```

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

### TypeScript VibeLogger Configuration with Interface and Partial (Option A)

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Illustrates a TypeScript option for configuration management using an interface with optional properties. This approach, often combined with `Partial<T>`, allows for flexible configuration where only a subset of properties needs to be provided, making it easy to override default settings.

```typescript
interface VibeLoggerConfig {
  correlationId?: string;
  logFile?: string;
  autoSave?: boolean;
  maxFileSizeMb?: number;
  keepLogsInMemory?: boolean;
  maxMemoryLogs?: number;
  createDirs?: boolean;
}

// Usage: new VibeLogger(config?: Partial<VibeLoggerConfig>)
```

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

### Proposed Package and Directory Structure

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Outlines the recommended file and directory organization for both Python and TypeScript implementations of the VibeLogger project, detailing module and component separation for better maintainability and scalability.

```text
python/vibelogger/
├── __init__.py
├── logger.py
├── config.py
├── handlers.py
└── formatters.py
```

```text
typescript/src/
├── index.ts
├── logger.ts
├── config.ts
├── types.ts
├── handlers/
│   ├── index.ts
│   └── winston.ts
├── formatters/
│   ├── index.ts
│   └── structured.ts
└── utils/
    ├── environment.ts
    └── fileSystem.ts
```

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

### API Reference: Creating VibeLogger Instances

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This section details the different factory functions available for creating logger instances: `createLogger` for basic configuration, `createFileLogger` for file-based logging, and `createEnvLogger` for environment variable-driven configuration.

```APIDOC
createLogger(options?: VibeLoggerConfig): VibeLogger
  options: Configuration object for the logger.
    correlationId: string - Custom correlation ID.
    keepLogsInMemory: boolean - Whether to keep logs in memory.
    autoSave: boolean - Whether to auto-save logs to file.

createFileLogger(projectName: string, options?: VibeLoggerConfig): VibeLogger
  projectName: string - Name of the project, used for file naming.
  options: Configuration object for the logger (optional).

createEnvLogger(): VibeLogger
  Initializes logger using VIBE_* environment variables.
```

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

### Configure AI for VibeCoding Logger Usage

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Provides instructions for AI assistants (e.g., Claude) on how to use the VibeCoding Logger library for project logging and where to find debugging data. This snippet is intended to be added to a CLAUDE.md file.

```markdown
### Project Logging
* Use vibelogger library for all logging needs
* vibelogger instruction: https://github.com/fladdict/vibe-logger/blob/main/README.md
* Check ./logs/<project_name>/ folder for debugging data when issues occur
```

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

### Configure VibeCoding Logger with Custom Settings (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Illustrates how to create a logger with a custom configuration, specifying log file path, maximum file size, auto-save, memory retention, and maximum in-memory logs.

```python
from vibelogger import create_logger, VibeLoggerConfig

config = VibeLoggerConfig(
    log_file="./logs/custom.log",
    max_file_size_mb=50,
    auto_save=True,
    keep_logs_in_memory=True,
    max_memory_logs=1000
)
logger = create_logger(config=config)
```

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

### Configure VibeCoding Logger with Custom Settings (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Illustrates how to create a VibeCoding Logger instance with custom configuration settings in Python. This includes specifying log file paths, maximum file sizes, auto-save behavior, and in-memory log retention limits using VibeLoggerConfig.

```python
from vibelogger import create_logger, VibeLoggerConfig

config = VibeLoggerConfig(
    log_file="./logs/custom.log",
    max_file_size_mb=50,
    auto_save=True,
    keep_logs_in_memory=True,
    max_memory_logs=1000
)
logger = create_logger(config=config)
```

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

### Configure VibeLogger using Environment Variables

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This snippet illustrates how to configure VibeLogger using environment variables, which is particularly useful for deployment scenarios. It shows common `VIBE_*` variables for setting log file paths, size limits, auto-save behavior, and memory management.

```bash
export VIBE_LOG_FILE=./logs/app.log
export VIBE_MAX_FILE_SIZE_MB=25
export VIBE_AUTO_SAVE=true
export VIBE_KEEP_LOGS_IN_MEMORY=true
export VIBE_MAX_MEMORY_LOGS=500
export VIBE_CORRELATION_ID=my-service-id
```

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

### API Reference: VibeLogger Logging Methods

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This section outlines the various logging methods available on a VibeLogger instance, categorized by log level. All methods return a Promise resolving to a `LogEntry` and support an optional `options` object for rich context.

```APIDOC
VibeLogger:
  debug(operation: string, message: string, options?: LogOptions): Promise<LogEntry>
  info(operation: string, message: string, options?: LogOptions): Promise<LogEntry>
  warning(operation: string, message: string, options?: LogOptions): Promise<LogEntry>
  error(operation: string, message: string, options?: LogOptions): Promise<LogEntry>
  critical(operation: string, message: string, options?: LogOptions): Promise<LogEntry>
  logException(operation: string, error: any, options?: LogOptions): Promise<LogEntry>
    operation: string - The operation name.
    message: string - The log message.
    error: any - The error object or value to log.
    options: LogOptions - Optional configuration for the log entry.
```

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

### Log Messages with Rich Context using VibeCoding Logger

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

Demonstrates the basic usage of VibeCoding Logger to create a file-based logger and log messages with rich, AI-optimized context. It shows how to include operation names, messages, contextual data, and human annotations for improved AI debugging.

```python
from vibelogger import create_file_logger

# Create logger with auto-save to timestamped file
logger = create_file_logger("my_project")

# Log with rich context for AI analysis
logger.info(
    operation="fetchUserProfile",
    message="Starting user profile fetch",
    context={"user_id": "123", "source": "api_endpoint"},
    human_note="AI-TODO: Check if user exists before fetching profile"
)

# Logs are automatically saved to ./logs/my_project/ folder
# AI can read these files when debugging is needed
```

```typescript
import { createFileLogger } from 'vibelogger';

// Create logger with auto-save to timestamped file
const logger = createFileLogger("my_project");

// Log with rich context for AI analysis
await logger.info(
    "fetchUserProfile",
    "Starting user profile fetch",
    {
        context: { user_id: "123", source: "api_endpoint" },
        human_note: "AI-TODO: Check if user exists before fetching profile"
    }
);

// Logs are automatically saved to ./logs/my_project/ folder
// AI can read these files when debugging is needed
```

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

### Python VibeLogger Configuration Management with Dataclass

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Shows the Python approach to defining logger configuration using a `@dataclass`. This structure allows for clear definition of configuration fields with optional default values, providing a concise and type-hinted way to manage settings.

```python
@dataclass
class VibeLoggerConfig:
    correlation_id: Optional[str] = None
    log_file: Optional[str] = None
    # ... other fields
```

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

### VibeCoding Logger Version Compatibility Standards

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Details the semantic versioning approach for the logger's API and the versioning strategy for the log format itself, including migration guidelines.

```APIDOC
Version Compatibility:
  Semantic Versioning:
    Major: Breaking changes to log format or core API
    Minor: New features, backwards compatible
    Patch: Bug fixes, internal improvements
  Log Format Versioning:
    Include format version in log metadata when schema changes
    Maintain backwards compatibility for at least 2 major versions
    Provide migration tools for format upgrades
```

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

### TypeScript VibeLogger Configuration with Class and Defaults (Option B)

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Presents another TypeScript option for configuration management using a class. This approach allows defining default values for properties directly within the class and merging provided options in the constructor, offering a more structured way to handle configuration and ensure all properties have a fallback value.

```typescript
class VibeLoggerConfig {
  correlationId?: string;
  logFile?: string;
  autoSave = true;
  maxFileSizeMb = 10;
  keepLogsInMemory = true;
  maxMemoryLogs = 1000;
  createDirs = true;

  constructor(options?: Partial<VibeLoggerConfig>) {
    Object.assign(this, options);
  }
}
```

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

### Python VibeCoding Logger Exception Handling Approach

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Illustrates the Python approach to logging exceptions, leveraging Python's built-in exception types and the `traceback` module to capture detailed stack traces. This method simplifies error information extraction due to Python's consistent exception structure.

```python
def log_exception(self, operation: str, exception: Exception, ...):
    # Python has built-in exception types
    stack_trace = traceback.format_exc()
```

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

### VibeCoding Logger Testing Requirements

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Outlines the necessary unit, integration, and performance testing areas for all VibeCoding Logger implementations.

```APIDOC
Testing Requirements:
  Unit Tests:
    Core logging functionality
    Configuration management
    File output and rotation
    Memory management
    Thread safety (where applicable)
  Integration Tests:
    Framework integration
    Standard logging library compatibility
    Cross-language log format validation
  Performance Tests:
    High-volume logging scenarios
    Memory usage under load
    File I/O performance
    Concurrent access patterns
```

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

### Collecting System Environment Information

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Defines structures and methods for collecting system environment details such as Python/Node.js version, operating system, platform, and architecture. The TypeScript implementation includes a utility for detecting the current JavaScript runtime environment (Node.js, browser, Deno, Bun).

```python
@dataclass
class EnvironmentInfo:
    python_version: str
    os: str
    platform: str
    architecture: str
```

```typescript
interface EnvironmentInfo {
  node_version: string;
  os: string;
  platform: string;
  architecture: string;
  runtime?: string;
}

class EnvironmentInfo {
  static collect(): EnvironmentInfo {
    return {
      node_version: process.version,
      os: require('os').platform(),
      platform: require('os').type(),
      architecture: require('os').arch(),
      runtime: this.detectRuntime()
    };
  }
  
  private static detectRuntime(): string {
    if (typeof process !== 'undefined' && process.versions?.node) return 'node';
    if (typeof window !== 'undefined') return 'browser';
    if (typeof Deno !== 'undefined') return 'deno';
    if (typeof Bun !== 'undefined') return 'bun';
    return 'unknown';
  }
}
```

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

### API Reference: LogOptions Interface

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This defines the `LogOptions` interface, which provides additional parameters for logging methods. It allows including rich context data, human-readable notes, AI-specific tasks, and forcing stack trace inclusion.

```APIDOC
interface LogOptions:
  context?: Record<string, any> - Rich context data for the log entry.
  humanNote?: string - Instructions or notes for human review or AI.
  aiTodo?: string - Specific tasks or actions for AI to consider.
  includeStack?: boolean - Forces inclusion of stack trace, even for non-errors.
```

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

### VibeCoding Logger Core API Methods

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines the essential logging and utility methods that all VibeCoding Logger implementations across different programming languages must provide, ensuring consistent functionality.

```APIDOC
// Basic logging
debug(operation, message, options?)
info(operation, message, options?)
warning(operation, message, options?)
error(operation, message, options?)
critical(operation, message, options?)

// Exception logging
logException(operation, exception, options?)

// Utility methods
getLogsForAI(filter?)
clearLogs()
```

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

### Configure Memory-Efficient Logging (Python)

Source: https://github.com/fladdict/vibe-logger/blob/main/python/README.md

Demonstrates how to configure the logger for long-running processes by disabling in-memory log storage to prevent out-of-memory issues.

```python
from vibelogger import VibeLoggerConfig, create_logger

# For long-running processes - disable memory storage
config = VibeLoggerConfig(
    log_file="./logs/production.log",
    keep_logs_in_memory=False,  # Don't store logs in memory
    auto_save=True
)
logger = create_logger(config=config)
```

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

### TypeScript VibeCoding Logger Exception Handling Solution

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Presents a proposed TypeScript solution for handling exceptions, designed to accommodate the varied nature of JavaScript errors and `unknown` thrown values. It includes a `logException` method to process different error types and an `extractErrorInfo` helper to normalize error messages, stack traces, and names across environments.

```typescript
logException(operation: string, error: Error | unknown, options?: LogOptions) {
  // Handle both Error objects and unknown thrown values
  const errorInfo = this.extractErrorInfo(error);
  // Normalize stack traces across Node.js/browser
}

private extractErrorInfo(error: unknown): ErrorInfo {
  if (error instanceof Error) {
    return { message: error.message, stack: error.stack, name: error.name };
  }
  // Handle primitive throws: throw "string", throw 42, etc.
  return { message: String(error), stack: undefined, name: 'UnknownError' };
}
```

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

### Core VibeCoding Logger API Methods

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Outlines the core API methods for the VibeCoding Logger, designed to closely match the Python version's interface. These methods provide functionalities for logging information, errors, and exceptions, as well as retrieving logs specifically formatted for AI analysis.

```APIDOC
logger.info(operation, message, options?)
logger.error(operation, message, options?)
logger.logException(operation, error, options?)
logger.getLogsForAI(operationFilter?)
```

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

### Python VibeCoding Logger File System Operations with Threading Lock

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Demonstrates the Python implementation for saving log entries to a file, utilizing `pathlib` for path manipulation and a `threading.Lock` to ensure thread-safe file access. This approach guarantees that only one thread writes to the log file at a time, preventing data corruption.

```python
from pathlib import Path
import threading

self._file_lock = threading.Lock()
with self._file_lock:
    with open(self.log_file, 'a', encoding='utf-8') as f:
        f.write(entry.to_json() + '\n')
```

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

### VibeCoding Logger File Naming and Location Specification

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines the standard naming convention and default storage location for log files generated by the VibeCoding Logger.

```APIDOC
File Naming:
  Pattern: `vibe_YYYYMMDD_HHMMSS.log`
  Example: `vibe_20250707_143052.log`
  Location: `./logs/{project_name}/` (default)
```

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

### TypeScript VibeCoding Logger Synchronous File Save (Option A)

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Provides a TypeScript option for saving log entries synchronously using `fs.writeFileSync`. This approach employs an `async-mutex` to ensure exclusive file access, mimicking Python's file locking behavior and simplifying logic, though it can block the event loop.

```typescript
import { writeFileSync } from 'fs';
import { Mutex } from 'async-mutex';

private fileMutex = new Mutex();

async saveToFile(entry: LogEntry): Promise<void> {
  await this.fileMutex.runExclusive(() => {
    writeFileSync(this.logFile, entry.toJson() + '\n', { flag: 'a', encoding: 'utf8' });
  });
}
```

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

### VibeCoding Logger Log Rotation Policy

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Outlines the default and configurable parameters for log file rotation, including size limits and retention.

```APIDOC
Log Rotation:
  Default: 10MB per file
  Configurable maximum file size
  Automatic timestamp-based rotation
  Keep rotated files for debugging history
```

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

### Naming Conventions and Data Conversion

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Illustrates the adopted naming conventions for VibeLogger: `snake_case` for Python and JSON fields, and `camelCase` for TypeScript code. It also demonstrates how TypeScript code converts `camelCase` parameters to `snake_case` for internal JSON representation to maintain consistency across languages.

```python
correlation_id, log_file, max_file_size_mb, get_logs_for_ai()
```

```typescript
correlationId, logFile, maxFileSizeMb, getLogsForAI()
```

```typescript
class VibeLogger {
  private correlationId: string;
  
  info(operation: string, message: string, options?: {
    context?: Record<string, any>;
    humanNote?: string;
    aiTodo?: string;
  }) {
    return new LogEntry({
      correlation_id: this.correlationId,
      human_note: options?.humanNote,
      ai_todo: options?.aiTodo
    });
  }
}
```

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

### VibeCoding Logger Cross-Language Log Format Compatibility Standards

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines the mandatory requirements for log format consistency across different language implementations, including JSON schema, field names, and timestamp format.

```APIDOC
Log Format Compatibility:
  All languages MUST produce logs that conform to the same JSON schema
  Field names MUST be identical across languages
  Timestamp format MUST be consistent (ISO 8601 UTC)
```

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

### VibeCoding Logger Structured Log Fields (Schema)

Source: https://github.com/fladdict/vibe-logger/blob/main/README.md

This section details the key fields within the VibeCoding Logger's structured JSON output, explaining their purpose and format. These fields are designed to provide comprehensive context for AI analysis and debugging.

```APIDOC
VibeCoding Log Entry Schema:
  timestamp: string (ISO format with UTC timezone)
    Description: The exact time the log entry was created.
  correlation_id: string
    Description: Links related operations across different parts of a request or system.
  operation: string
    Description: Describes what the code was attempting to accomplish at the time of logging.
  context: object
    Description: Contains function arguments, local variables, and relevant state information.
  environment: object
    Description: Provides runtime environment details necessary for reproducing issues.
  source: string
    Description: Specifies the exact file location and function name where the log was generated.
  human_note: string (optional)
    Description: Natural language instructions or notes intended for human review or AI guidance.
  ai_todo: string (optional)
    Description: Specific analysis requests or tasks for an AI assistant to perform based on the log entry.
```

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

### VibeCoding Logger Context Field Standards

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines common context fields and naming conventions for enriching log entries with relevant operational data.

```APIDOC
Context Standards:
  Use consistent field naming when possible
  Common context fields:
    user_id: User identifier
    request_id: Request identifier
    session_id: Session identifier
    ip_address: Client IP address
    user_agent: Client user agent
    duration_ms: Operation duration in milliseconds
```

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

### TypeScript VibeCoding Logger Asynchronous File Save (Option B)

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Presents an asynchronous TypeScript option for saving log entries using `fs.promises.appendFile`. This approach is more idiomatic for Node.js, utilizing an `async-mutex` for controlled, non-blocking file writes. It offers better performance for high-throughput logging by not blocking the event loop.

```typescript
import { appendFile } from 'fs/promises';

async saveToFile(entry: LogEntry): Promise<void> {
  await this.fileMutex.runExclusive(async () => {
    await appendFile(this.logFile, entry.toJson() + '\n', 'utf8');
  });
}
```

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

### VibeCoding Logger File Content Specification

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Specifies the format, encoding, and line separation for log file content, ensuring consistent parsing.

```APIDOC
File Content:
  Format: One JSON object per line (JSONL)
  Encoding: UTF-8
  Line separator: `\n`
```

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

### VibeCoding Logger Optional Fields JSON Schema

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines additional, non-mandatory fields that can be included in a VibeCoding Logger entry to provide richer context, debugging information, or specific instructions for AI.

```JSON
{
  "source": "user_service.py:42 in get_user_profile()",
  "stack_trace": "TypeError: Cannot read properties...",
  "human_note": "AI-TODO: Check if user exists before fetching",
  "ai_todo": "Analyze user lookup failures and suggest improvements"
}
```

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

### VibeCoding Logger Security Considerations

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Addresses critical security aspects such as sensitive data protection, PII masking, and file permission management for log files.

```APIDOC
Security Considerations:
  Sensitive Data Protection:
    Implement PII masking capabilities
    Provide hooks for custom data sanitization
    Avoid logging secrets, tokens, passwords by default
    Support configurable field blacklisting
  File Permissions:
    Log files should have restricted permissions (600 or 644)
    Directory creation should respect umask
    Provide configuration for custom file permissions
```

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

### Advanced VibeLogger: Implementing Correlation Tracking

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/README.md

This snippet shows how to use a consistent `correlationId` across a series of related logging operations. This allows for easy tracing of a single request or process flow through multiple log entries, aiding in debugging and analysis.

```typescript
const correlationId = `request-${Date.now()}`;
const logger = createLogger({ correlationId });

await logger.info('request_start', 'Processing API request');
await logger.info('auth_check', 'Validating credentials');
await logger.info('business_logic', 'Executing core logic');
await logger.info('request_end', 'Request completed');

// All logs will have the same correlation_id
```

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

### VibeCoding Logger Internationalization Standards

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Specifies requirements for character encoding and timezone handling to ensure global compatibility of log data.

```APIDOC
Internationalization:
  Character Encoding:
    UTF-8 for all text content
    Support for Unicode in log messages and context
    Proper handling of multi-byte characters
  Timezone Handling:
    Always use UTC for timestamps
    Support timezone conversion utilities
    Document timezone handling in examples
```

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

### VibeCoding Logger Required Fields JSON Schema

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Defines the mandatory fields for a VibeCoding Logger entry, ensuring core information is always present for AI analysis and correlation.

```JSON
{
  "timestamp": "2025-07-07T08:36:42.123Z",
  "level": "INFO",
  "correlation_id": "req_abc123",
  "operation": "fetchUserProfile",
  "message": "User profile retrieved successfully",
  "context": {},
  "environment": {}
}
```

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

### Define VibeCoding Logger JSON Log Entry Interface in TypeScript

Source: https://github.com/fladdict/vibe-logger/blob/main/typescript/DESIGN_DISCUSSION.md

Defines the `LogEntry` interface in TypeScript, specifying the structured format for log entries to ensure JSON compatibility with the Python VibeCoding Logger. It includes essential fields like timestamp, level, correlation ID, operation, message, context, environment details, and optional fields for source, stack trace, human notes, and AI tasks.

```typescript
interface LogEntry {
  timestamp: string;           // ISO 8601 UTC
  level: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
  correlation_id: string;      // UUID or custom
  operation: string;           // What the code was trying to do
  message: string;            // Human readable message
  context: Record<string, any>; // Rich context data
  environment: EnvironmentInfo; // Runtime environment
  source?: string;            // File location and function
  stack_trace?: string;       // Error stack trace
  human_note?: string;        // Instructions for AI
  ai_todo?: string;          // Specific AI tasks
}
```

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

### VibeCoding Logger Correlation ID Standards

Source: https://github.com/fladdict/vibe-logger/blob/main/docs/SPECIFICATION.md

Specifies the format and propagation requirements for correlation IDs to enable tracing across service boundaries.

```APIDOC
Correlation ID Standards:
  UUID v4 format recommended
  Must be unique per request/session
  Should be propagated across service boundaries
  Support for custom correlation ID injection
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.