perf-skill 0.2.1 → 0.3.0

package/.claude-plugin/README.md

@@ -0,0 +1,53 @@
+# perf-skill for Claude Marketplace
+
+This directory contains the Claude Marketplace plugin configuration for perf-skill.
+
+## Files
+
+- `plugin.json` - Main plugin manifest defining skills, installation, and compatibility
+- `marketplace.json` - Marketplace listing metadata (description, category, triggers)
+
+## Publishing to Claude Marketplace
+
+### Prerequisites
+
+1. Ensure the npm package is published: `npm publish`
+2. Verify the SKILL.md is included in the npm package
+3. Test the installation: `npx perf-skill init --ai claude`
+
+### Submission
+
+1. Visit [Claude Marketplace Developer Portal](https://claude.ai/marketplace/developer)
+2. Submit this repository for review
+3. The marketplace will validate:
+   - Plugin manifest schema
+   - Installation process
+   - Skill file structure
+   - Documentation quality
+
+### Local Testing
+
+```bash
+# Install locally for testing
+npx perf-skill init --ai claude --scope project
+
+# Verify skill installation
+cat .claude/skills/perf-skill/SKILL.md
+```
+
+## Trigger Configuration
+
+The `marketplace.json` defines when Claude should suggest this skill:
+
+- **File patterns**: `*.pb.gz`, `*.pprof`
+- **Keywords**: profile, pprof, cpu, heap, memory, performance, slow, bottleneck
+- **Intents**: "analyze profile", "why is my app slow", "compare performance"
+
+## Version Sync
+
+Keep `version` in `plugin.json` synchronized with `package.json` version.
+
+## Support
+
+- Issues: https://github.com/skillsland/perf-skill/issues
+- Documentation: https://github.com/skillsland/perf-skill#readme

package/.claude-plugin/marketplace.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://claude.ai/plugins/v1/marketplace.schema.json",
+  "listing": {
+    "name": "perf-skill",
+    "tagline": "AI-powered pprof profile analysis",
+    "shortDescription": "Convert CPU and heap profiles to structured evidence for performance optimization",
+    "longDescription": "perf-skill is a deterministic evidence generator for pprof profiles. It converts .pb.gz CPU and heap profiles into structured Markdown and JSON, enabling AI agents to provide optimization recommendations based on factual evidence.\n\n## Features\n\n- **Analyze** - Convert profiles to structured hotspot reports\n- **Diff** - Compare two profiles to find regressions\n- **Profile** - Capture CPU and heap profiles from Node.js apps\n- **Evidence-first** - Produces structured data for AI agents to interpret\n\n## Use Cases\n\n- Identify CPU bottlenecks in Node.js applications\n- Find memory leaks and allocation hotspots\n- Compare before/after profiles to verify optimizations\n- Generate evidence for performance code reviews",
+    "category": "developer-tools",
+    "subcategory": "performance",
+    "icon": "chart-line",
+    "screenshots": [],
+    "documentation": "https://github.com/skillsland/perf-skill#readme",
+    "support": {
+      "url": "https://github.com/skillsland/perf-skill/issues",
+      "email": null
+    },
+    "pricing": {
+      "type": "free"
+    },
+    "stats": {
+      "installs": 0,
+      "rating": null,
+      "reviews": 0
+    }
+  },
+  "triggers": {
+    "filePatterns": [
+      "*.pb.gz",
+      "*.pprof"
+    ],
+    "keywords": [
+      "profile",
+      "pprof",
+      "cpu",
+      "heap",
+      "memory",
+      "performance",
+      "slow",
+      "bottleneck",
+      "hotspot",
+      "optimize",
+      "regression"
+    ],
+    "intents": [
+      "analyze profile",
+      "why is my app slow",
+      "compare performance",
+      "find memory leak",
+      "cpu profiling",
+      "heap analysis"
+    ]
+  },
+  "requirements": {
+    "runtime": "node",
+    "minVersion": "20.0.0",
+    "dependencies": []
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://claude.ai/plugins/v1/plugin.schema.json",
+  "name": "perf-skill",
+  "version": "0.3.0",
+  "description": "Performance profile evidence extractor - Convert pprof CPU and heap profiles to structured Markdown and JSON for AI-powered performance analysis",
+  "author": "skillsland",
+  "license": "MIT",
+  "homepage": "https://github.com/skillsland/perf-skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skillsland/perf-skill.git"
+  },
+  "keywords": [
+    "performance",
+    "profiling",
+    "pprof",
+    "cpu",
+    "heap",
+    "memory",
+    "optimization",
+    "analysis",
+    "node.js",
+    "evidence"
+  ],
+  "skills": [
+    {
+      "name": "perf-skill",
+      "path": ".claude/skills/perf-skill/SKILL.md",
+      "description": "Analyze pprof CPU and heap profiles to identify performance bottlenecks"
+    }
+  ],
+  "install": {
+    "type": "npm",
+    "package": "perf-skill",
+    "postInstall": "npx perf-skill init --ai claude"
+  },
+  "compatibility": {
+    "claude": ">=1.0.0"
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,164 @@
+# CLAUDE.md - Developer Guide for perf-skill
+
+This document provides guidelines for AI agents and developers working with the perf-skill codebase.
+
+## Project Overview
+
+perf-skill is an AI skill that converts pprof CPU and heap profiles (.pb.gz) into structured Markdown and JSON evidence. It follows a **deterministic, evidence-first** design philosophy - the tool produces factual data without AI dependencies, while AI agents can optionally enhance the output with recommendations.
+
+## Repository Structure
+
+```
+perf-skill/
+├── src/
+│   ├── cli/              # CLI implementation
+│   │   ├── main.ts       # CLI entry point
+│   │   ├── init.ts       # Skill installation logic
+│   │   ├── platforms.ts  # Multi-platform configurations
+│   │   └── template.ts   # Template rendering engine
+│   ├── parser/           # pprof parsing logic
+│   ├── renderer/         # Markdown/JSON output
+│   ├── profile/          # Node.js profiling
+│   └── index.ts          # Library exports
+├── test/                 # Test files
+├── SKILL.md              # Main skill definition
+├── .claude-plugin/       # Claude Marketplace configs
+├── package.json
+└── README.md
+```
+
+## Key Commands
+
+### Development
+
+```bash
+# Build
+npm run build
+
+# Run CLI in development
+npm run cli -- analyze profile.pb.gz
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+### CLI Usage
+
+```bash
+# Analyze a profile
+npx perf-skill analyze cpu.pb.gz -o report.md
+
+# Compare profiles
+npx perf-skill diff base.pb.gz current.pb.gz
+
+# Profile and analyze a Node.js app
+npx perf-skill run app.js --duration 10s
+
+# Install skill for a platform
+npx perf-skill init --ai cursor
+npx perf-skill init --ai claude
+npx perf-skill init --ai all
+```
+
+## Architecture Decisions
+
+### Evidence-First Design
+
+- The core analyzer produces structured data without AI
+- LLM integration is optional (via `--ai` flag)
+- All outputs are reproducible and deterministic
+
+### Multi-Platform Support
+
+The `init` command supports 13+ AI platforms:
+- Claude, Cursor, Windsurf, Copilot, Kiro
+- Codex, Qoder, Roo Code, Gemini, Trae
+- OpenCode, Continue, CodeBuddy
+
+Each platform has its own configuration in `src/cli/platforms.ts`.
+
+### Template System
+
+Platform-specific skill files are generated from:
+1. Base `SKILL.md` content
+2. Platform configuration (frontmatter, sections)
+3. Template engine in `src/cli/template.ts`
+
+## Contributing Guidelines
+
+### Code Style
+
+- Use TypeScript strict mode
+- Follow existing patterns for error handling
+- Add tests for new features
+- Update SKILL.md for user-facing changes
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+node --test --import tsx test/parser.test.ts
+```
+
+### Pull Request Process
+
+1. Create feature branch from `main`
+2. Make changes with descriptive commits
+3. Ensure tests pass: `npm test`
+4. Ensure lint passes: `npm run lint`
+5. Update documentation if needed
+6. Submit PR with clear description
+
+## Common Tasks
+
+### Adding a New Platform
+
+1. Add platform to `AI_PLATFORMS` array in `src/cli/platforms.ts`
+2. Add configuration to `PLATFORM_CONFIGS` object
+3. Test installation: `npm run cli -- init --ai <platform>`
+
+### Updating SKILL.md
+
+1. Edit the root `SKILL.md` file
+2. Test rendering: `npm run cli -- init --ai claude --dry-run`
+3. Verify frontmatter is valid YAML
+
+### Publishing
+
+```bash
+# Bump version
+npm version patch|minor|major
+
+# Publish to npm
+npm publish
+
+# Sync Claude Marketplace
+# - Update version in .claude-plugin/plugin.json
+# - Submit to marketplace for review
+```
+
+## Debugging
+
+### Common Issues
+
+1. **Profile parsing fails**: Check file is valid gzip-compressed protobuf
+2. **Source code not included**: Verify `--source-dir` path exists
+3. **Platform install fails**: Check directory permissions
+
+### Verbose Mode
+
+```bash
+npx perf-skill analyze profile.pb.gz --verbose
+```
+
+## Security Considerations
+
+- Profile data may contain sensitive information
+- Use `--redact` (default) to sanitize paths
+- Never commit real profiles to the repository

package/README.md

@@ -4,14 +4,23 @@
 [![npm version](https://badge.fury.io/js/perf-skill.svg)](http://badge.fury.io/js/perf-skill)
 ![license](https://img.shields.io/npm/l/perf-skill)
 
-AI‑assisted pprof toolkit for CPU/heap profiles: convert .pb.gz/.pprof to structured Markdown, compare profiles for regressions, and optionally generate evidence‑backed recommendations.
+**Deterministic** pprof evidence extractor for CPU/heap profiles: convert .pb.gz/.pprof to structured Markdown and JSON, compare profiles for regressions, and produce evidence that any AI agent can use for optimization recommendations.
+
+## Philosophy
+
+This tool follows the "evidence generator" pattern:
+
+1. **Deterministic by default** — All operations produce consistent, reproducible output without external API calls
+2. **LLM-agnostic** — The tool produces structured evidence (hotspots, call paths, metrics); the host agent (Claude, Cursor, etc.) performs reasoning
+3. **No network by default** — No data leaves your machine unless you explicitly enable AI analysis with `--ai`
+4. **Skill-ready** — Designed to work as a Claude Skill / Cursor Agent Skill that provides facts for the agent to interpret
 
 ## Features
 
-- **Convert**: Transform pprof profiles to structured Markdown
-- **Analyze**: Get AI-powered optimization recommendations
-- **Diff**: Compare two profiles to find regressions
-- **Multi-format**: Library, CLI, and HTTP API
+- **Convert** (default): Transform pprof profiles to structured Markdown and JSON evidence
+- **Analyze**: Optionally get AI-powered recommendations with `--ai` flag
+- **Diff**: Compare two profiles to find regressions and improvements
+- **Multiple interfaces**: Library API and CLI for direct integration
 
 ## Installation
 
@@ -25,32 +34,56 @@ Or run directly with npx:
 npx perf-skill analyze profile.pb.gz
 ```
 
+### AI Platform Integration
+
+Install perf-skill as a skill for your preferred AI coding assistant:
+
+```bash
+# Claude Code / Claude Desktop
+npx perf-skill init --ai claude
+
+# Cursor
+npx perf-skill init --ai cursor
+
+# GitHub Copilot
+npx perf-skill init --ai copilot
+
+# All supported platforms at once
+npx perf-skill init --ai all
+```
+
+See [Supported Platforms](#supported-platforms) for the full list.
+
 ## Quick Start
 
 ### CLI Usage
 
 ```bash
-# Convert profile to markdown (fast, no LLM)
-perf-skill convert cpu.pb.gz -o report.md
+# Analyze profile → structured evidence (default, no LLM, no network)
+perf-skill analyze cpu.pb.gz -o report.md
+
+# Analyze with explicit AI recommendations (requires API key)
+perf-skill analyze cpu.pb.gz --ai -o report.md
 
-# Full analysis with AI recommendations
-perf-skill analyze cpu.pb.gz --mode analyze
+# Convert-only command (always deterministic)
+perf-skill convert cpu.pb.gz -o report.md
 
-# Profile a Node entry (CPU, 10s) and analyze
+# Profile a Node entry (CPU, 10s) → evidence output
 perf-skill run slow.mjs --duration 10s
 
+# Profile with AI recommendations
+perf-skill run slow.mjs --duration 10s --ai
+
 # CPU + Heap profiling (separate reports)
 perf-skill run slow.mjs --heap --output cpu.md --heap-output heap.md
 
 # Compare two profiles
 perf-skill diff base.pb.gz current.pb.gz -o diff.md
 
-# Start HTTP server
-perf-skill server --port 3000
-
-# Install SKILL.md for Cursor (user or project)
-perf-skill init --cursor
-perf-skill init --cursor --scope project
+# Install skill for your AI platform
+perf-skill init --ai claude
+perf-skill init --ai cursor --scope project
+perf-skill init --ai all  # Install to all supported platforms
 
 # Install SKILL.md to a custom directory
 perf-skill init ./skills/perf-skill
@@ -59,14 +92,15 @@ perf-skill init ./skills/perf-skill
 ### Programmatic Usage
 
 ```typescript
-import { analyze, diff } from "perf-skill-skill";
+import { analyze, diff } from "perf-skill";
 
-// Convert only (no LLM)
-const result = await analyze("cpu.pb.gz", { mode: "convert-only" });
-console.log(result.markdown);
-console.log(result.hotspots);
+// Default: deterministic evidence extraction (no LLM, no network)
+const result = await analyze("cpu.pb.gz");
+console.log(result.markdown);    // Structured Markdown report
+console.log(result.hotspots);    // Array of hotspot objects
+console.log(result.raw.llmStatus); // "skipped" - no LLM was invoked
 
-// Full analysis with AI recommendations
+// Explicit AI analysis (requires API key)
 const fullResult = await analyze("cpu.pb.gz", {
   mode: "analyze",
   context: {
@@ -76,8 +110,9 @@ const fullResult = await analyze("cpu.pb.gz", {
   },
 });
 console.log(fullResult.recommendations);
+console.log(fullResult.raw.llmStatus); // "success" or "failed"
 
-// Compare two profiles
+// Compare two profiles (always deterministic)
 const diffResult = await diff("base.pb.gz", "current.pb.gz", {
   normalize: "scale-to-base-total",
 });
@@ -85,43 +120,27 @@ console.log(diffResult.regressions);
 console.log(diffResult.improvements);
 ```
 
-### HTTP API
-
-```bash
-# Start server
-perf-skill server
-
-# Start server with security overrides
-perf-skill server --no-cors --no-helmet --rate-limit --rate-limit-max 120 --rate-limit-window-ms 60000
-
-# Analyze profile
-curl -X POST http://localhost:3000/v1/pprof/analyze \
-  -F "file=@cpu.pb.gz"
-
-# Compare profiles
-curl -X POST http://localhost:3000/v1/pprof/diff \
-  -F "base=@base.pb.gz" \
-  -F "current=@current.pb.gz"
-```
-
 ## CLI Options
 
 ### `perf-skill analyze <profile.pb.gz>`
 
-| Option                 | Description                                      | Default    |
-| ---------------------- | ------------------------------------------------ | ---------- |
-| `-f, --format`         | Output format: `summary`, `detailed`, `adaptive` | `adaptive` |
-| `-t, --type`           | Profile type: `cpu`, `heap`, `auto`              | `auto`     |
-| `-o, --output`         | Output markdown file                             | stdout     |
-| `-j, --json`           | Output JSON results file                         | -          |
-| `-m, --mode`           | `convert-only` or `analyze`                      | `analyze`  |
-| `-s, --source-dir`     | Source directory for code context                | -          |
-| `--max-hotspots`       | Maximum hotspots to show                         | `10`       |
-| `--llm-provider`       | LLM provider: `openai`, `anthropic`, etc.        | `openai`   |
-| `--llm-model`          | LLM model name                                   | `gpt-5.2`  |
-| `--service`            | Service name for context                         | -          |
-| `--scenario`           | Scenario description                             | -          |
-| `--redact/--no-redact` | Redact sensitive information                     | `true`     |
+| Option                 | Description                                      | Default        |
+| ---------------------- | ------------------------------------------------ | -------------- |
+| `-f, --format`         | Output format: `summary`, `detailed`, `adaptive` | `adaptive`     |
+| `-t, --type`           | Profile type: `cpu`, `heap`, `auto`              | `auto`         |
+| `-o, --output`         | Output markdown file                             | stdout         |
+| `-j, --json`           | Output JSON results file                         | -              |
+| `-m, --mode`           | `convert-only` or `analyze`                      | `convert-only` |
+| `--ai`                 | Enable AI-powered recommendations (requires key) | `false`        |
+| `-s, --source-dir`     | Source directory for code context                | -              |
+| `--max-hotspots`       | Maximum hotspots to show                         | `10`           |
+| `--llm-provider`       | LLM provider: `openai`, `anthropic`, etc.        | `openai`       |
+| `--llm-model`          | LLM model name                                   | `gpt-5.2`      |
+| `--service`            | Service name for context                         | -              |
+| `--scenario`           | Scenario description                             | -              |
+| `--redact/--no-redact` | Redact sensitive information                     | `true`         |
+
+> **Note:** By default, `analyze` produces deterministic evidence output (no LLM). Use `--ai` to explicitly enable AI recommendations.
 
 ### `perf-skill run <entry> [entryArgs...]`
 
@@ -139,7 +158,8 @@ curl -X POST http://localhost:3000/v1/pprof/diff \
 | `-t, --type`            | Profile type: `cpu`, `heap`, `auto`              | `auto`                      |
 | `-o, --output`          | Output markdown file                             | stdout                      |
 | `-j, --json`            | Output JSON results file                         | -                           |
-| `-m, --mode`            | `convert-only` or `analyze`                      | `analyze`                   |
+| `-m, --mode`            | `convert-only` or `analyze`                      | `convert-only`              |
+| `--ai`                  | Enable AI-powered recommendations (requires key) | `false`                     |
 | `-s, --source-dir`      | Source directory for code context                | -                           |
 | `--max-hotspots`        | Maximum hotspots to show                         | `10`                        |
 | `--llm-provider`        | LLM provider: `openai`, `anthropic`, etc.        | `openai`                    |
@@ -150,6 +170,8 @@ curl -X POST http://localhost:3000/v1/pprof/diff \
 
 When `--heap` is enabled and `--output` is omitted, `perf-skill` writes `cpu.md` and `heap.md` instead of printing to stdout.
 
+> **Note:** By default, `run` produces deterministic evidence output (no LLM). Use `--ai` to explicitly enable AI recommendations.
+
 ### `perf-skill profile <entry> [entryArgs...]`
 
 | Option                  | Description                                 | Default      |
@@ -173,14 +195,49 @@ When `--heap` is enabled and `--output` is omitted, `perf-skill` writes `cpu.md`
 
 ### `perf-skill init [target]`
 
-Install the bundled `SKILL.md` to a target directory or Cursor skills folder.
+Install the `SKILL.md` to a target directory or AI platform.
+
+| Option         | Description                            | Default   |
+| -------------- | -------------------------------------- | --------- |
+| `-a, --ai`     | Target AI platform (see below)         | -         |
+| `-c, --cursor` | Install into Cursor (legacy)           | `false`   |
+| `--scope`      | Installation scope: `user` or `project`| `project` |
+| `-f, --force`  | Overwrite existing `SKILL.md`          | `false`   |
+| `--dry-run`    | Show destination without writing files | `false`   |
+| `--offline`    | Use bundled assets only                | `false`   |
+
+#### Supported Platforms
+
+| Platform    | Command                         | Install Location                        |
+| ----------- | ------------------------------- | --------------------------------------- |
+| Claude      | `--ai claude`                   | `.claude/skills/perf-skill/SKILL.md`    |
+| Cursor      | `--ai cursor`                   | `.cursor/skills/perf-skill/SKILL.md`    |
+| Windsurf    | `--ai windsurf`                 | `.windsurf/skills/perf-skill/SKILL.md`  |
+| Copilot     | `--ai copilot`                  | `.github/copilot/perf-skill.md`         |
+| Kiro        | `--ai kiro`                     | `.kiro/skills/perf-skill/SKILL.md`      |
+| Codex       | `--ai codex`                    | `.codex/skills/perf-skill/SKILL.md`     |
+| Qoder       | `--ai qoder`                    | `.qodo/skills/perf-skill/SKILL.md`      |
+| Roo Code    | `--ai roocode`                  | `.roo/skills/perf-skill/SKILL.md`       |
+| Gemini      | `--ai gemini`                   | `.gemini/skills/perf-skill/SKILL.md`    |
+| Trae        | `--ai trae`                     | `.trae/skills/perf-skill/SKILL.md`      |
+| OpenCode    | `--ai opencode`                 | `.opencode/skills/perf-skill/SKILL.md`  |
+| Continue    | `--ai continue`                 | `.continue/skills/perf-skill/SKILL.md`  |
+| CodeBuddy   | `--ai codebuddy`                | `.codebuddy/skills/perf-skill/SKILL.md` |
+| **All**     | `--ai all`                      | Installs to all platforms               |
+
+```bash
+# Install for Claude
+npx perf-skill init --ai claude
+
+# Install for Cursor (project scope)
+npx perf-skill init --ai cursor --scope project
 
-| Option         | Description                            | Default |
-| -------------- | -------------------------------------- | ------- |
-| `-c, --cursor` | Install into Cursor skills folder      | `false` |
-| `--scope`      | Cursor scope: `user` or `project`      | `user`  |
-| `-f, --force`  | Overwrite existing `SKILL.md`          | `false` |
-| `--dry-run`    | Show destination without writing files | `false` |
+# Install for all supported platforms
+npx perf-skill init --ai all
+
+# Preview installation without writing
+npx perf-skill init --ai cursor --dry-run
+```
 
 ## Output Formats
 
@@ -209,9 +266,9 @@ Full context with call trees and source code.
 
 Summary with drill-down sections and anchor links for navigation.
 
-## AI Recommendations
+## AI Recommendations (Optional)
 
-When using `--mode analyze`, the tool generates structured recommendations:
+When using `--ai` (or `--mode analyze`), the tool invokes an LLM to generate structured recommendations:
 
 ```typescript
 interface Recommendation {
@@ -226,6 +283,8 @@ interface Recommendation {
 
 All recommendations must reference evidence from the profile (function names, percentages, locations).
 
+> **Note:** For Skill/Agent usage, it is recommended to let the host agent (Claude, Cursor, etc.) generate recommendations based on the deterministic evidence output. This keeps the tool LLM-agnostic and allows the agent to apply its own reasoning.
+
 ## Profile Diff
 
 Compare two profiles to identify performance regressions:
@@ -288,12 +347,6 @@ writeFileSync("heap.pb.gz", gzipSync(heapProfile.encode()));
 | `LLM_RETRY_DELAY_MS`   | Base retry delay in ms                          |
 | `LOG_LEVEL`            | Logging level: `debug`, `info`, `warn`, `error` |
 | `LOG_FORMAT`           | Log format: `text`, `json`                      |
-| `CORS_ENABLED`         | Enable CORS (`true`/`false`)                    |
-| `CORS_ORIGIN`          | CORS origin(s), comma-separated or `*`          |
-| `HELMET_ENABLED`       | Enable Helmet (`true`/`false`)                  |
-| `RATE_LIMIT_ENABLED`   | Enable rate limiting (`true`/`false`)           |
-| `RATE_LIMIT_MAX`       | Rate limit max requests per window              |
-| `RATE_LIMIT_WINDOW_MS` | Rate limit window size in ms                    |
 
 Example:
 
@@ -331,47 +384,13 @@ By default, the tool redacts:
 
 Disable with `--no-redact` or `redact: false`.
 
-### Server Mode
-
-In HTTP server mode:
-
-- Source code inclusion is disabled by default
-- File size limits are enforced
-- Only `.pb.gz` files are accepted
-
-Security defaults (configurable via env or server options):
-
-- CORS enabled (set `CORS_ENABLED=false` to disable)
-- Helmet enabled (set `HELMET_ENABLED=false` to disable)
-- Rate limiting enabled (default 60 req/min, set `RATE_LIMIT_ENABLED=false` or `RATE_LIMIT_MAX=0` to disable)
-
-Server CLI flags (override env defaults):
-
-- `--cors/--no-cors`
-- `--cors-origin <origin>` (comma-separated or `*`)
-- `--helmet/--no-helmet`
-- `--rate-limit/--no-rate-limit`
-- `--rate-limit-max <n>`
-- `--rate-limit-window-ms <ms>`
-
-ServerOptions (programmatic):
-
-```typescript
-const server = await createServer({
-  enableCors: true,
-  corsOrigin: "https://example.com",
-  enableHelmet: true,
-  enableRateLimit: true,
-  rateLimitMax: 60,
-  rateLimitWindowMs: 60_000,
-});
-```
-
 ## Requirements
 
 - Node.js >= 22.6.0
-- For AI analysis: API key for OpenAI, Anthropic, or compatible provider
 - CPU profiling uses bundled `@datadog/pprof` (native module) on supported platforms
+- **Optional:** For AI recommendations (`--ai`), an API key for OpenAI, Anthropic, or compatible provider
+
+> **No API key required for default usage.** The tool produces complete, actionable evidence without any external dependencies.
 
 ## API Reference