selftune 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- **Real-time improvement signal detection** — `prompt-log` hook detects user corrections ("why didn't you use X?") and explicit skill requests via pure regex patterns. Signals are logged to `~/.claude/improvement_signals.jsonl` with skill name extraction from installed skills.
+- **Signal-reactive orchestration** — `session-stop` hook checks for pending improvement signals and spawns a focused `selftune orchestrate --max-skills 2` run in the background. Respects a 30-minute lockfile to prevent concurrent runs.
+- **Signal-aware candidate selection** — Orchestrator reads pending signals and boosts priority for mentioned skills (+150 per signal, capped at +450). Signaled skills bypass the minimum evidence gate and the "UNGRADED with 0 missed queries" gate.
+- **Orchestrate lockfile** — `acquireLock()`/`releaseLock()` with PID+timestamp in `~/.claude/.orchestrate.lock`. 30-minute stale threshold prevents deadlocks from crashed runs.
+- **Signal consumption** — After an orchestrate run completes, consumed signals are marked with `consumed: true`, `consumed_at`, and `consumed_by_run` so they don't affect subsequent runs.
+
+## [0.2.0] — 2026-03-08
+
+### Added
+
+- **Full skill body evolution** — Teacher-student model for evolving routing tables and complete skill bodies with 3-gate validation (structural, trigger, quality)
+- **Synthetic eval generation** — `selftune eval generate --synthetic --skill <name> --skill-path <path>` generates eval sets from SKILL.md via LLM without needing real session logs. Solves cold-start for new skills.
+- **Batch trigger validation** — `validateProposalBatched()` batches 10 queries per LLM call (configurable via `TRIGGER_CHECK_BATCH_SIZE`). ~10x faster evolution loops. Sequential `validateProposalSequential()` kept for backward compat.
+- **Cheap-loop evolution mode** — `selftune evolve --cheap-loop` uses haiku for proposal generation and validation, sonnet only for the final deployment gate. New `--gate-model` and `--proposal-model` flags for manual per-stage control.
+- **Validation model selection** — `--validation-model` flag on `evolve` and `evolve body` commands (default: `haiku`).
+- **Proposal model selection** — `--proposal-model` flag on `evolve`, passed through to `generateProposal()` and `generateMultipleProposals()`.
+- **Gate validation dependency injection** — `gateValidateProposal` added to `EvolveDeps` for testability.
+- **Auto-activation system** — `auto-activate.ts` UserPromptSubmit hook detects when selftune should run and outputs formatted suggestions; session state tracking prevents repeated nags; PAI coexistence support
+- **Skill change guard** — `skill-change-guard.ts` PreToolUse hook detects Write/Edit to SKILL.md files and suggests running `selftune watch`
+- **Evolution memory** — 3-file persistence system at `~/.selftune/memory/` (context.md, plan.md, decisions.md) survives context resets; auto-maintained by evolve, rollback, and watch commands
+- **Specialized agents** — 4 purpose-built Claude Code agents: diagnosis-analyst, pattern-analyst, evolution-reviewer, integration-guide
+- **Enforcement guardrails** — `evolution-guard.ts` PreToolUse hook blocks SKILL.md edits on actively monitored skills unless `selftune watch` has been run recently
+- **Integration guide** — Comprehensive `docs/integration-guide.md` with project-type patterns (single-skill, multi-skill, monorepo, Codex-only, OpenCode-only, mixed)
+- **Settings templates** — `templates/single-skill-settings.json`, `templates/multi-skill-settings.json`, `templates/activation-rules-default.json`
+- **Enhanced init** — `selftune init` now detects workspace structure (skill count, monorepo layout) and suggests appropriate template
+- **Dashboard server** — `selftune dashboard --serve` launches live Bun.serve server with SSE auto-refresh, action buttons (watch/evolve/rollback), and evolution timeline
+- **Activation rules engine** — Configurable trigger rules for auto-activation (grading thresholds, stale evolutions, regression detection)
+- **Sandbox test harness** (`tests/sandbox/run-sandbox.ts`): Exercises all CLI commands and hooks against fixture data in an isolated `/tmp` environment. Runs in ~400ms with 10/10 tests passing.
+- **Devcontainer-based LLM testing** (`.devcontainer/` + `tests/sandbox/docker/`): Based on the official Claude Code devcontainer reference. Uses `claude -p` with `--dangerously-skip-permissions` for unattended LLM-dependent testing (grade, evolve, watch). No API key required — uses existing Claude subscription.
+- **Realistic test fixtures**: 3 skills from skills.sh (find-skills, frontend-design, ai-image-generation) with 15 sessions, 30 queries, 7 skill usage records, and evolution audit history.
+- **Hook integration tests**: All 3 Claude Code hooks (prompt-log, skill-eval, session-stop) tested via stdin payload injection.
+
+### Changed
+
+- `validateProposal()` now delegates to `validateProposalBatched()` by default (was sequential).
+- `hooks-to-evals.ts` `cliMain()` is now async to support synthetic generation.
+- `EvolveOptions` extended with `validationModel`, `cheapLoop`, `gateModel`, `proposalModel`.
+- `EvolveResult` extended with `gateValidation`.
+
 ## [0.1.4] - 2026-03-01
 
 ### Added
@@ -12,6 +55,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - `selftune status` — CLI skill health summary with pass rates, trends, and system health
 - `selftune last` — Quick insight from the most recent session
 - `selftune dashboard` — Skill-health-centric HTML dashboard with grid view and drill-down
+- `selftune ingest claude` — Claude Code transcript replay for retroactive log backfill
+- `selftune contribute` — Opt-in anonymized data export for community contribution
 - CI/CD workflows: publish, auto-bump, CodeQL, scorecard
 - FOSS governance: LICENSE (MIT), CODE_OF_CONDUCT, CONTRIBUTING, SECURITY
 - npm package configuration with CJS bin entry point
@@ -20,7 +65,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- CLI entry point with 10 commands: `init`, `evals`, `grade`, `evolve`, `rollback`, `watch`, `doctor`, `ingest-codex`, `ingest-opencode`, `wrap-codex`
+- CLI entry point with 10 commands: `init`, `eval generate`, `grade`, `evolve`, `evolve rollback`, `watch`, `doctor`, `ingest codex`, `ingest opencode`, `ingest wrap-codex`
 - Agent auto-detection for Claude Code, Codex, and OpenCode
 - Telemetry hooks for Claude Code (`prompt-log`, `skill-eval`, `session-stop`)
 - Codex wrapper and batch ingestor for rollout logs

package/README.md

@@ -1,316 +1,164 @@
-[![CI](https://github.com/WellDunDun/selftune/actions/workflows/ci.yml/badge.svg)](https://github.com/WellDunDun/selftune/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/WellDunDun/selftune/actions/workflows/codeql.yml/badge.svg)](https://github.com/WellDunDun/selftune/actions/workflows/codeql.yml)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/WellDunDun/selftune/badge)](https://securityscorecards.dev/viewer/?uri=github.com/WellDunDun/selftune)
-[![npm version](https://img.shields.io/npm/v/selftune)](https://www.npmjs.com/package/selftune)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/selftune?activeTab=dependencies)
-[![Bun](https://img.shields.io/badge/runtime-bun%20%7C%20node-black)](https://bun.sh)
+<div align="center">
+
+<img src="assets/logo.svg" alt="selftune logo" width="80" />
+
+# selftune
 
-# selftune — Skill Observability & Continuous Improvement CLI
+**Self-improving skills for AI agents.**
 
+[![CI](https://github.com/selftune-dev/selftune/actions/workflows/ci.yml/badge.svg)](https://github.com/selftune-dev/selftune/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/selftune-dev/selftune/actions/workflows/codeql.yml/badge.svg)](https://github.com/selftune-dev/selftune/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/selftune-dev/selftune/badge)](https://securityscorecards.dev/viewer/?uri=github.com/selftune-dev/selftune)
 [![npm version](https://img.shields.io/npm/v/selftune)](https://www.npmjs.com/package/selftune)
-[![CI](https://github.com/WellDunDun/selftune/actions/workflows/ci.yml/badge.svg)](https://github.com/WellDunDun/selftune/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue.svg)](https://www.typescriptlang.org/)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/selftune?activeTab=dependencies)
 [![Bun](https://img.shields.io/badge/runtime-bun%20%7C%20node-black)](https://bun.sh)
 
-Observe real sessions, detect missed triggers, grade execution quality, and automatically evolve skill descriptions toward the language real users actually use.
+Your agent skills learn how you work. Detect what's broken. Fix it automatically.
 
-Works with **Claude Code**, **Codex**, and **OpenCode**.
+**[Install](#install)** · **[Use Cases](#built-for-how-you-actually-work)** · **[How It Works](#how-it-works)** · **[Commands](#commands)** · **[Platforms](#platforms)** · **[Docs](docs/integration-guide.md)**
 
-```
-Observe → Detect → Diagnose → Propose → Validate → Deploy → Watch → Repeat
-```
+</div>
 
 ---
 
-## Install
+Your skills don't understand how you talk. You say "make me a slide deck" and nothing happens — no error, no log, no signal. selftune watches your real sessions, learns how you actually speak, and rewrites skill descriptions to match. Automatically.
 
-```bash
-npx selftune@latest doctor
-```
+Works with **Claude Code** (primary). Codex, OpenCode, and OpenClaw adapters are experimental. Zero runtime dependencies.
 
-Or install globally:
+## Install
 
 ```bash
-npm install -g selftune
-selftune doctor
+npx skills add selftune-dev/selftune
 ```
 
-Requires [Bun](https://bun.sh) or Node.js 18+ with [tsx](https://github.com/privatenumber/tsx).
-
----
-
-## Why
-
-Agent skills are static, but users are not. When a skill undertriggers — when someone says "make me a slide deck" and the pptx skill doesn't fire — that failure is invisible. The user concludes "AI doesn't follow directions" rather than recognizing the skill description doesn't match how real people talk.
-
-selftune closes this feedback loop.
-
----
-
-## What It Does
+Then tell your agent: **"initialize selftune"**
 
-| Capability | Description |
-|---|---|
-| **Session telemetry** | Captures per-session process metrics across all three platforms |
-| **False negative detection** | Surfaces queries where a skill should have fired but didn't |
-| **Eval set generation** | Converts hook logs into trigger eval sets with real usage as ground truth |
-| **Session grading** | 3-tier evaluation (Trigger / Process / Quality) using the agent you already have |
-| **Skill evolution** | Proposes improved descriptions, validates them, deploys with audit trail |
-| **Post-deploy monitoring** | Watches evolved skills for regressions, auto-rollback on pass rate drops |
-
----
+Two minutes. No API keys. No external services. No configuration ceremony. Uses your existing agent subscription. You'll see which skills are undertriggering.
 
-## Setup
-
-### 1. Add the skill
+**CLI only** (no skill, just the CLI):
 
 ```bash
-npx skills add WellDunDun/selftune
+npx selftune@latest doctor
 ```
 
-### 2. Initialize
+## Before / After
 
-Tell your agent: **"initialize selftune"**
+<p align="center">
+  <img src="./assets/BeforeAfter.gif" alt="Before: 47% pass rate → After: 89% pass rate" width="800">
+</p>
 
-The agent will install the CLI (`npm install -g selftune`) if needed, run `selftune init` to bootstrap config, install hooks, and verify with `selftune doctor`.
+selftune learned that real users say "slides", "deck", "presentation for Monday" — none of which matched the original skill description. It rewrote the description to match how people actually talk. Validated against the eval set. Deployed with a backup. Done.
 
----
-
-## Development
-
-For contributors running from source.
-
-### 1. Initialize
-
-```bash
-npx selftune@latest init
-```
+## Built for How You Actually Work
 
-The `init` command auto-detects your agent environment (Claude Code, Codex, or OpenCode), resolves the CLI path, determines the LLM mode, and writes config to `~/.selftune/config.json`. All subsequent commands read from this config.
+**I write and use my own skills** — Your skill descriptions don't match how you actually talk. Tell your agent "improve my skills" and selftune learns your language from real sessions, evolves descriptions to match, and validates before deploying. No manual tuning.
 
-Use `--agent claude_code|codex|opencode` to override detection, `--llm-mode agent|api` to override LLM mode, or `--force` to reinitialize.
+**I publish skills others install** — Your skill works for you, but every user talks differently. selftune ships skills that get better for every user automatically — adapting descriptions to how each person actually works.
 
-### 4. Install hooks (Claude Code)
+**I manage an agent setup with many skills** — You have 15+ skills installed. Some work. Some don't. Some conflict. Tell your agent "how are my skills doing?" and selftune gives you a health dashboard and automatically improves the skills that aren't keeping up.
 
-If `init` reports hooks are not installed, merge the entries from `skill/settings_snippet.json` into `~/.claude/settings.json`. Derive hook script paths from the `cli_path` field in `~/.selftune/config.json` — the hooks directory is at `dirname(cli_path)/hooks/`.
+## How It Works
 
-### 5. Verify setup
+<p align="center">
+  <img src="./assets/FeedbackLoop.gif" alt="Observe → Detect → Evolve → Watch" width="800">
+</p>
 
-```bash
-selftune doctor
-```
+A continuous feedback loop that makes your skills learn and adapt. Automatically. Your agent runs everything — you just install the skill and talk naturally.
 
-Doctor checks log file health, hook installation, schema validity, and config status.
+**Observe** — Hooks capture every query and which skills fired. On Claude Code, hooks install automatically during `selftune init`. Backfill existing transcripts with `selftune ingest claude`.
 
-### Platform-Specific Notes
+**Detect** — Finds the gap between how you talk and how your skills are described. You say "make me a slide deck" and your pptx skill stays silent — selftune catches that mismatch. Real-time correction signals ("why didn't you use X?") are detected and trigger immediate improvement.
 
-**Claude Code** — Hooks capture telemetry automatically after installation. Zero configuration once hooks are in `settings.json`.
+**Evolve** — Rewrites skill descriptions — and full skill bodies — to match how you actually work. Cheap-loop mode uses haiku for the loop, sonnet for the gate (~80% cost reduction). Teacher-student body evolution with 3-gate validation. Automatic backup.
 
-**Codex** — Use the wrapper for real-time capture or the batch ingestor for historical logs:
-```bash
-selftune wrap-codex -- <your codex args>
-selftune ingest-codex
-```
+**Watch** — After deploying changes, selftune monitors skill trigger rates. If anything regresses, it rolls back automatically.
 
-**OpenCode** — Backfill historical sessions from SQLite:
-```bash
-selftune ingest-opencode
-```
+**Automate** — Run `selftune cron setup` to install OS-level scheduling. selftune syncs, evaluates, evolves, and watches on a schedule — no manual intervention needed.
 
-All platforms write to the same shared JSONL log schema at `~/.claude/`.
+## What's New in v0.2.0
 
----
+- **Full skill body evolution** — Beyond descriptions: evolve routing tables and entire skill bodies using teacher-student model with structural, trigger, and quality gates
+- **Synthetic eval generation** — `selftune eval generate --synthetic` generates eval sets from SKILL.md via LLM, no session logs needed. Solves cold-start: new skills get evals immediately.
+- **Cheap-loop evolution** — `selftune evolve --cheap-loop` uses haiku for proposal generation and validation, sonnet only for the final deployment gate. ~80% cost reduction.
+- **Batch trigger validation** — Validation now batches 10 queries per LLM call instead of one-per-query. ~10x faster evolution loops.
+- **Per-stage model control** — `--validation-model`, `--proposal-model`, and `--gate-model` flags give fine-grained control over which model runs each evolution stage.
+- **Auto-activation system** — Hooks detect when selftune should run and suggest actions
+- **Enforcement guardrails** — Blocks SKILL.md edits on monitored skills unless `selftune watch` has been run
+- **Live dashboard server** — `selftune dashboard --serve` with SSE auto-refresh and action buttons
+- **Evolution memory** — Persists context, plans, and decisions across context resets
+- **4 specialized agents** — Diagnosis analyst, pattern analyst, evolution reviewer, integration guide
+- **Sandbox test harness** — Comprehensive automated test coverage, including devcontainer-based LLM testing
 
 ## Commands
 
-```
-selftune <command> [options]
-```
-
-| Command | Purpose |
+Your agent runs these — you just say what you want ("improve my skills", "show the dashboard").
+
+| Group | Command | What it does |
+|-------|---------|-------------|
+| | `selftune status` | See which skills are undertriggering and why |
+| | `selftune orchestrate` | Run the full autonomous loop (sync → evolve → watch) |
+| | `selftune dashboard` | Open the visual skill health dashboard |
+| | `selftune doctor` | Health check: logs, hooks, config, permissions |
+| **ingest** | `selftune ingest claude` | Backfill from Claude Code transcripts |
+| | `selftune ingest codex` | Import Codex rollout logs (experimental) |
+| **grade** | `selftune grade --skill <name>` | Grade a skill session with evidence |
+| | `selftune grade baseline --skill <name>` | Measure skill value vs no-skill baseline |
+| **evolve** | `selftune evolve --skill <name>` | Propose, validate, and deploy improved descriptions |
+| | `selftune evolve body --skill <name>` | Evolve full skill body or routing table |
+| | `selftune evolve rollback --skill <name>` | Rollback a previous evolution |
+| **eval** | `selftune eval generate --skill <name>` | Generate eval sets (`--synthetic` for cold-start) |
+| | `selftune eval unit-test --skill <name>` | Run or generate skill-level unit tests |
+| | `selftune eval composability --skill <name>` | Detect conflicts between co-occurring skills |
+| | `selftune eval import` | Import external eval corpus from [SkillsBench](https://github.com/benchflow-ai/skillsbench) |
+| **auto** | `selftune cron setup` | Install OS-level scheduling (cron/launchd/systemd) |
+| | `selftune watch --skill <name>` | Monitor after deploy. Auto-rollback on regression. |
+
+Full command reference: `selftune --help`
+
+## Why Not Just Rewrite Skills Manually?
+
+| Approach | Problem |
 |---|---|
-| `init` | Auto-detect agent environment, write `~/.selftune/config.json` |
-| `grade --skill <name>` | Grade a session (3-tier: trigger, process, quality) |
-| `evals --skill <name>` | Generate eval set from real usage logs |
-| `evals --list-skills` | Show logged skills and query counts |
-| `evolve --skill <name> --skill-path <path>` | Analyze failures, propose and deploy improved description |
-| `rollback --skill <name> --skill-path <path>` | Restore pre-evolution description |
-| `watch --skill <name> --skill-path <path>` | Monitor post-deploy pass rates, detect regressions |
-| `status` | Show skill health summary (pass rates, trends, missed queries) |
-| `last` | Show quick insight from the most recent session |
-| `doctor` | Health checks on logs, hooks, config, and schema |
-| `dashboard` | Open skill-health-centric HTML dashboard in browser |
-| `ingest-codex` | Batch ingest Codex rollout logs |
-| `ingest-opencode` | Backfill historical OpenCode sessions from SQLite |
-| `wrap-codex -- <args>` | Real-time Codex wrapper with telemetry |
-
-No separate API key required — grading and evolution use whatever agent CLI you already have installed (Claude Code, Codex, or OpenCode).
-
-See `skill/Workflows/` for detailed step-by-step guides for each command.
-
----
-
-## How It Works
-
-### Telemetry Capture
-
-```
-Claude Code (hooks):                 OpenCode (hooks):
-  UserPromptSubmit → prompt-log.ts     message.*        → opencode-prompt-log.ts
-  PostToolUse      → skill-eval.ts     tool.execute.after → opencode-skill-eval.ts
-  Stop             → session-stop.ts   session.idle     → opencode-session-stop.ts
-          │                                    │
-          └──────────┬─────────────────────────┘
-                     ▼
-          Shared JSONL Log Schema (~/.claude/)
-            ├── all_queries_log.jsonl
-            ├── skill_usage_log.jsonl
-            └── session_telemetry_log.jsonl
-
-Codex (wrapper/ingestor — hooks not yet available):
-  codex-wrapper.ts  (real-time tee of JSONL stream)
-  codex-rollout.ts  (batch ingest from rollout logs)
-          │
-          └──→ Same shared JSONL schema
-```
-
-### Eval & Grading
-
-```
-selftune evals cross-references the two query logs:
-  Positives  = skill_usage_log entries for target skill
-  Negatives  = all_queries_log entries NOT in positives
-
-selftune grade reads:
-  session_telemetry_log → process metrics (tool calls, errors, turns)
-  transcript JSONL       → what actually happened
-  expectations           → what should have happened
-```
-
-### Evolution Loop
-
-```
-selftune evolve:
-  1. Load eval set (or generate from logs)
-  2. Extract failure patterns (missed queries grouped by invocation type)
-  3. Generate improved description via LLM
-  4. Validate against eval set (must improve, <5% regression)
-  5. Deploy updated SKILL.md + PR + audit trail
-
-selftune watch:
-  Monitor pass rate over sliding window of recent sessions
-  Alert (or auto-rollback) on regression > threshold
-```
-
----
-
-## Architecture
-
-```
-cli/selftune/
-├── index.ts                     CLI entry point (command router)
-├── init.ts                      Agent detection, config bootstrap
-├── types.ts, constants.ts       Shared interfaces and constants
-├── observability.ts             Health checks (doctor command)
-├── status.ts                    Skill health summary (status command)
-├── last.ts                      Last session insight (last command)
-├── dashboard.ts                 HTML dashboard builder (dashboard command)
-├── utils/                       JSONL, transcript parsing, LLM calls, schema validation
-├── hooks/                       Claude Code + OpenCode telemetry capture
-├── ingestors/                   Codex adapters + OpenCode backfill
-├── eval/                        False negative detection, eval set generation
-├── grading/                     3-tier session grading (agent or API mode)
-├── evolution/                   Failure extraction, proposal, validation, deploy, rollback
-└── monitoring/                  Post-deploy regression detection
-
-dashboard/
-└── index.html                   Skill-health-centric HTML dashboard template
-
-skill/
-├── SKILL.md                     Routing table (~120 lines)
-├── settings_snippet.json        Claude Code hook config template
-├── references/                  Domain knowledge (logs, grading methodology, taxonomy)
-└── Workflows/                   Step-by-step guides (1 per command)
-```
-
-Dependencies flow forward only: `shared → hooks/ingestors → eval → grading → evolution → monitoring`. Enforced by `lint-architecture.ts`.
-
-Config persists at `~/.selftune/config.json` (written by `init`, read by all commands via skill workflows).
-
-See [ARCHITECTURE.md](ARCHITECTURE.md) for the full domain map and module rules.
-
----
-
-## Log Schema
-
-Three append-only JSONL files at `~/.claude/`:
-
-| File | Record type | Key fields |
-|---|---|---|
-| `all_queries_log.jsonl` | `QueryLogRecord` | `timestamp`, `session_id`, `query`, `source?` |
-| `skill_usage_log.jsonl` | `SkillUsageRecord` | `timestamp`, `session_id`, `skill_name`, `query`, `triggered` |
-| `session_telemetry_log.jsonl` | `SessionTelemetryRecord` | `timestamp`, `session_id`, `tool_calls`, `bash_commands`, `skills_triggered`, `errors_encountered` |
-| `evolution_audit_log.jsonl` | `EvolutionAuditEntry` | `timestamp`, `proposal_id`, `action`, `details`, `eval_snapshot?` |
-
-The `source` field identifies the platform: `claude_code`, `codex`, or `opencode`.
-
----
+| Rewrite the description yourself | No data on how users actually talk. No validation. No regression detection. |
+| Add "ALWAYS invoke when..." directives | Brittle. One agent rewrite away from breaking. |
+| Force-load skills on every prompt | Doesn't fix the description. Expensive band-aid. |
+| **selftune** | Learns from real usage, rewrites descriptions to match how you work, validates against eval sets, auto-rollbacks on regressions. |
 
-## Development
+## Different Layer, Different Problem
 
-```bash
-make check    # lint + architecture lint + all tests
-make lint     # biome check + architecture lint
-make test     # bun test
-```
+LLM observability tools trace API calls. Infrastructure tools monitor servers. Neither knows whether the right skill fired for the right person. selftune does — and fixes it automatically.
 
-Zero runtime dependencies. Uses Bun built-ins only.
+selftune is complementary to these tools, not competitive. They trace what happens inside the LLM. selftune makes sure the right skill is called in the first place.
 
----
+| Dimension | selftune | Langfuse | LangSmith | OpenLIT |
+|-----------|----------|----------|-----------|---------|
+| **Layer** | Skill-specific | LLM call | Agent trace | Infrastructure |
+| **Detects** | Missed triggers, false negatives, skill conflicts | Token usage, latency | Chain failures | System metrics |
+| **Improves** | Descriptions, body, and routing automatically | — | — | — |
+| **Setup** | Zero deps, zero API keys | Self-host or cloud | Cloud required | Helm chart |
+| **Price** | Free (MIT) | Freemium | Paid | Free |
+| **Unique** | Self-improving skills + auto-rollback | Prompt management | Evaluations | Dashboards |
 
-## Tips
+## Platforms
 
-- Run `selftune init` first — everything else reads from the config it writes.
-- Let logs accumulate over several days before running evals — more diverse real queries = more reliable signal.
-- All hooks are silent (exit 0) and take <50ms. Negligible overhead.
-- Logs are append-only JSONL. Safe to delete to start fresh, or archive old files.
-- Use `--max 75` to increase eval set size once you have enough data.
-- Use `--seed 123` for a different random sample of negatives.
-- Use `--dry-run` with `evolve` to preview proposals without deploying.
-- The `doctor` command checks log health, hook presence, config status, and schema validity.
+**Claude Code** (fully supported) — Hooks install automatically. `selftune ingest claude` backfills existing transcripts. This is the primary supported platform.
 
----
+**Codex** (experimental) — `selftune ingest wrap-codex -- <args>` or `selftune ingest codex`. Adapter exists but is not actively tested.
 
-## Contributing
+**OpenCode** (experimental) — `selftune ingest opencode`. Adapter exists but is not actively tested.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture rules, and PR guidelines.
+**OpenClaw** (experimental) — `selftune ingest openclaw` + `selftune cron setup` for autonomous evolution. Adapter exists but is not actively tested.
 
-Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+Requires [Bun](https://bun.sh) or Node.js 18+. No extra API keys.
 
 ---
 
-## Security
-
-To report a vulnerability, see [SECURITY.md](SECURITY.md).
+<div align="center">
 
----
-
-## Sponsor
-
-If selftune saves you time, consider [sponsoring the project](https://github.com/sponsors/WellDunDun).
-
----
+[Architecture](ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Integration Guide](docs/integration-guide.md) · [Sponsor](https://github.com/sponsors/WellDunDun)
 
-## Milestones
+MIT licensed. Free forever. Primary support for Claude Code; experimental adapters for Codex, OpenCode, and OpenClaw.
 
-| Version | Scope | Status |
-|---|---|---|
-| v0.1 | Hooks, ingestors, shared schema, eval generation | Done |
-| v0.2 | Session grading, grader skill | Done |
-| v0.3 | Evolution loop (propose, validate, deploy, rollback) | Done |
-| v0.4 | Post-deploy monitoring, regression detection | Done |
-| v0.5 | Agent-first skill restructure, `init` command, config bootstrap | Done |
-| v0.6 | Three-layer observability: `status`, `last`, redesigned dashboard | Done |
+</div>