logging

# Plugin Logging Guide

Implement structured, JSONL logging in SideQuest plugins using the `@side-quest/core/logging` factory.

## When to Use This Skill

- Adding logging to a new plugin
- Migrating a plugin to structured logging
- Debugging plugin behavior via logs
- Setting up log rotation or analysis
- Questions about logging best practices

## Quick Start

### 1. Add Dependency

```json
// package.json
{
  "dependencies": {
    "@side-quest/core": "workspace:*"
  }
}
```

### 2. Create Logger Module

```typescript
// src/logger.ts
import { createPluginLogger } from "@side-quest/core/logging";

export const {
  initLogger,
  createCorrelationId,
  getSubsystemLogger,
  logDir,
  logFile,
} = createPluginLogger({
  name: "my-plugin",
  subsystems: ["scraper", "api", "cache"],
});

// Export typed subsystem loggers
export const scraperLogger = getSubsystemLogger("scraper");
export const apiLogger = getSubsystemLogger("api");
export const cacheLogger = getSubsystemLogger("cache");
```

### 3. Initialize at Entry Points

```typescript
// src/index.ts (CLI entry point)
import { initLogger, createCorrelationId, scraperLogger } from "./logger";

await initLogger();

const cid = createCorrelationId();
scraperLogger.info`Starting scrape operation ${cid}`;
```

### 4. Use Correlation IDs

```typescript
// Pass cid through function calls
async function scrape(url: string, cid: string) {
  scraperLogger.debug`Fetching ${url} ${cid}`;
  try {
    const result = await fetch(url);
    scraperLogger.info`Fetched ${url} status=${result.status} ${cid}`;
    return result;
  } catch (error) {
    scraperLogger.error`Failed to fetch ${url}: ${error} ${cid}`;
    throw error;
  }
}
```

## Log Levels

| Level | When to Use |
|-------|-------------|
| `debug` | Detailed diagnostic info: selector attempts, parsing steps, cache hits |
| `info` | Normal operations: start/complete, item counts, timing |
| `warning` | Degraded operation: fallbacks, edge cases, retries |
| `error` | Failur