selftune 0.2.0 → 0.2.2

package/packages/telemetry-contract/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@selftune/telemetry-contract",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Canonical telemetry schema, types, and validators for selftune",
+  "type": "module",
+  "license": "MIT",
+  "author": "Daniel Petro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selftune-dev/selftune.git",
+    "directory": "packages/telemetry-contract"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./types": "./src/types.ts",
+    "./validators": "./src/validators.ts"
+  }
+}

package/packages/telemetry-contract/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./validators.js";

package/packages/telemetry-contract/src/types.ts

@@ -0,0 +1,163 @@
+export const CANONICAL_SCHEMA_VERSION = "2.0" as const;
+export type CanonicalSchemaVersion = typeof CANONICAL_SCHEMA_VERSION;
+
+export const CANONICAL_PLATFORMS = ["claude_code", "codex", "opencode", "openclaw"] as const;
+export type CanonicalPlatform = (typeof CANONICAL_PLATFORMS)[number];
+
+export const CANONICAL_CAPTURE_MODES = [
+  "hook",
+  "replay",
+  "wrapper",
+  "batch_ingest",
+  "repair",
+] as const;
+export type CanonicalCaptureMode = (typeof CANONICAL_CAPTURE_MODES)[number];
+
+export const CANONICAL_SOURCE_SESSION_KINDS = [
+  "interactive",
+  "replayed",
+  "synthetic",
+  "repaired",
+] as const;
+export type CanonicalSourceSessionKind = (typeof CANONICAL_SOURCE_SESSION_KINDS)[number];
+
+export const CANONICAL_PROMPT_KINDS = [
+  "user",
+  "continuation",
+  "task_notification",
+  "teammate_message",
+  "system_instruction",
+  "tool_output",
+  "meta",
+  "unknown",
+] as const;
+export type CanonicalPromptKind = (typeof CANONICAL_PROMPT_KINDS)[number];
+
+export const CANONICAL_INVOCATION_MODES = ["explicit", "implicit", "inferred", "repaired"] as const;
+export type CanonicalInvocationMode = (typeof CANONICAL_INVOCATION_MODES)[number];
+
+export const CANONICAL_COMPLETION_STATUSES = [
+  "completed",
+  "failed",
+  "interrupted",
+  "cancelled",
+  "unknown",
+] as const;
+export type CanonicalCompletionStatus = (typeof CANONICAL_COMPLETION_STATUSES)[number];
+
+export const CANONICAL_RECORD_KINDS = [
+  "session",
+  "prompt",
+  "skill_invocation",
+  "execution_fact",
+  "normalization_run",
+] as const;
+export type CanonicalRecordKind = (typeof CANONICAL_RECORD_KINDS)[number];
+
+export interface CanonicalRawSourceRef {
+  path?: string;
+  line?: number;
+  event_type?: string;
+  raw_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CanonicalRecordBase {
+  record_kind: CanonicalRecordKind;
+  schema_version: CanonicalSchemaVersion;
+  normalizer_version: string;
+  normalized_at: string;
+  platform: CanonicalPlatform;
+  capture_mode: CanonicalCaptureMode;
+  raw_source_ref: CanonicalRawSourceRef;
+}
+
+export interface CanonicalSessionRecordBase extends CanonicalRecordBase {
+  source_session_kind: CanonicalSourceSessionKind;
+  session_id: string;
+}
+
+export interface CanonicalSessionRecord extends CanonicalSessionRecordBase {
+  record_kind: "session";
+  started_at?: string;
+  ended_at?: string;
+  external_session_id?: string;
+  parent_session_id?: string;
+  agent_id?: string;
+  agent_type?: string;
+  agent_cli?: string;
+  session_key?: string;
+  channel?: string;
+  workspace_path?: string;
+  repo_root?: string;
+  repo_remote?: string;
+  branch?: string;
+  commit_sha?: string;
+  permission_mode?: string;
+  approval_policy?: string;
+  sandbox_policy?: string;
+  provider?: string;
+  model?: string;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalPromptRecord extends CanonicalSessionRecordBase {
+  record_kind: "prompt";
+  prompt_id: string;
+  occurred_at: string;
+  prompt_text: string;
+  prompt_hash?: string;
+  prompt_kind: CanonicalPromptKind;
+  is_actionable: boolean;
+  prompt_index?: number;
+  parent_prompt_id?: string;
+  source_message_id?: string;
+}
+
+export interface CanonicalSkillInvocationRecord extends CanonicalSessionRecordBase {
+  record_kind: "skill_invocation";
+  skill_invocation_id: string;
+  occurred_at: string;
+  matched_prompt_id?: string;
+  skill_name: string;
+  skill_path?: string;
+  skill_version_hash?: string;
+  invocation_mode: CanonicalInvocationMode;
+  triggered: boolean;
+  confidence: number;
+  tool_name?: string;
+  tool_call_id?: string;
+}
+
+export interface CanonicalExecutionFactRecord extends CanonicalSessionRecordBase {
+  record_kind: "execution_fact";
+  occurred_at: string;
+  prompt_id?: string;
+  tool_calls_json: Record<string, number>;
+  total_tool_calls: number;
+  bash_commands_redacted: string[];
+  assistant_turns: number;
+  errors_encountered: number;
+  input_tokens?: number;
+  output_tokens?: number;
+  duration_ms?: number;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalNormalizationRunRecord extends CanonicalRecordBase {
+  record_kind: "normalization_run";
+  run_id: string;
+  run_at: string;
+  raw_records_seen: number;
+  canonical_records_written: number;
+  repair_applied: boolean;
+}
+
+export type CanonicalRecord =
+  | CanonicalSessionRecord
+  | CanonicalPromptRecord
+  | CanonicalSkillInvocationRecord
+  | CanonicalExecutionFactRecord
+  | CanonicalNormalizationRunRecord;

package/packages/telemetry-contract/src/validators.ts

@@ -0,0 +1,109 @@
+import {
+  CANONICAL_CAPTURE_MODES,
+  CANONICAL_COMPLETION_STATUSES,
+  CANONICAL_INVOCATION_MODES,
+  CANONICAL_PLATFORMS,
+  CANONICAL_PROMPT_KINDS,
+  CANONICAL_RECORD_KINDS,
+  CANONICAL_SCHEMA_VERSION,
+  CANONICAL_SOURCE_SESSION_KINDS,
+  type CanonicalRawSourceRef,
+  type CanonicalRecord,
+} from "./types.js";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasString(value: Record<string, unknown>, key: string): boolean {
+  return typeof value[key] === "string" && value[key].length > 0;
+}
+
+function includesValue<T extends readonly string[]>(values: T, value: unknown): value is T[number] {
+  return typeof value === "string" && values.includes(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isNumberRecord(value: unknown): value is Record<string, number> {
+  return isObject(value) && Object.values(value).every(isFiniteNumber);
+}
+
+function hasSessionScope(value: Record<string, unknown>): boolean {
+  return (
+    includesValue(CANONICAL_SOURCE_SESSION_KINDS, value.source_session_kind) &&
+    hasString(value, "session_id")
+  );
+}
+
+export function isCanonicalRawSourceRef(value: unknown): value is CanonicalRawSourceRef {
+  return isObject(value);
+}
+
+export function isCanonicalRecord(value: unknown): value is CanonicalRecord {
+  if (!isObject(value)) return false;
+  if (value.schema_version !== CANONICAL_SCHEMA_VERSION) return false;
+  if (!includesValue(CANONICAL_RECORD_KINDS, value.record_kind)) return false;
+  if (!includesValue(CANONICAL_PLATFORMS, value.platform)) return false;
+  if (!includesValue(CANONICAL_CAPTURE_MODES, value.capture_mode)) return false;
+  if (!hasString(value, "normalizer_version")) return false;
+  if (!hasString(value, "normalized_at")) return false;
+  if (!isCanonicalRawSourceRef(value.raw_source_ref)) return false;
+
+  switch (value.record_kind) {
+    case "session":
+      return (
+        hasSessionScope(value) &&
+        (value.completion_status === undefined ||
+          includesValue(CANONICAL_COMPLETION_STATUSES, value.completion_status))
+      );
+    case "prompt":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "prompt_id") &&
+        hasString(value, "occurred_at") &&
+        hasString(value, "prompt_text") &&
+        includesValue(CANONICAL_PROMPT_KINDS, value.prompt_kind) &&
+        typeof value.is_actionable === "boolean"
+      );
+    case "skill_invocation":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "skill_invocation_id") &&
+        hasString(value, "occurred_at") &&
+        (value.matched_prompt_id === undefined || hasString(value, "matched_prompt_id")) &&
+        hasString(value, "skill_name") &&
+        includesValue(CANONICAL_INVOCATION_MODES, value.invocation_mode) &&
+        typeof value.triggered === "boolean" &&
+        isFiniteNumber(value.confidence)
+      );
+    case "execution_fact":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "occurred_at") &&
+        isNumberRecord(value.tool_calls_json) &&
+        isFiniteNumber(value.total_tool_calls) &&
+        isStringArray(value.bash_commands_redacted) &&
+        isFiniteNumber(value.assistant_turns) &&
+        isFiniteNumber(value.errors_encountered) &&
+        (value.completion_status === undefined ||
+          includesValue(CANONICAL_COMPLETION_STATUSES, value.completion_status))
+      );
+    case "normalization_run":
+      return (
+        hasString(value, "run_id") &&
+        hasString(value, "run_at") &&
+        isFiniteNumber(value.raw_records_seen) &&
+        isFiniteNumber(value.canonical_records_written) &&
+        typeof value.repair_applied === "boolean"
+      );
+    default:
+      return false;
+  }
+}

package/skill/SKILL.md

@@ -19,6 +19,11 @@ description: >
 Observe real agent sessions, detect missed triggers, grade execution quality,
 and evolve skill descriptions toward the language real users actually use.
 
+**You are the operator.** The user installed this skill so YOU can manage their
+skill health autonomously. They will say things like "set up selftune",
+"improve my skills", or "how are my skills doing?" — and you route to the
+correct workflow below. The user does not run CLI commands directly; you do.
+
 ## Bootstrap
 
 If `~/.selftune/config.json` does not exist, read `Workflows/Initialize.md`
@@ -32,63 +37,75 @@ selftune <command> [options]
 ```
 
 Most commands output deterministic JSON. Parse JSON output for machine-readable commands.
-`selftune dashboard` is an exception: it generates an HTML artifact and may print
-informational progress lines.
+`selftune dashboard` is an exception: `--export` generates an HTML artifact, while
+`--serve` starts a local server; both may print informational progress lines.
 
 ## Quick Reference
 
 ```bash
-selftune grade    --skill <name> [--expectations "..."] [--agent <name>]
-selftune evals    --skill <name> [--list-skills] [--stats] [--max N]
-selftune evolve   --skill <name> --skill-path <path> [--dry-run]
-selftune rollback --skill <name> --skill-path <path> [--proposal-id <id>]
+# Ingest group
+selftune ingest claude   [--since DATE] [--dry-run] [--force] [--verbose]
+selftune ingest codex                                                          # (experimental)
+selftune ingest opencode                                                       # (experimental)
+selftune ingest openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
+selftune ingest wrap-codex -- <codex args>                                     # (experimental)
+
+# Grade group
+selftune grade auto      --skill <name> [--expectations "..."] [--agent <name>]
+selftune grade baseline  --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]
+
+# Evolve group
+selftune evolve          --skill <name> --skill-path <path> [--dry-run]
+selftune evolve body     --skill <name> --skill-path <path> --target <routing_table|full_body> [--dry-run]
+selftune evolve rollback --skill <name> --skill-path <path> [--proposal-id <id>]
+
+# Eval group
+selftune eval generate      --skill <name> [--list-skills] [--stats] [--max N]
+selftune eval unit-test      --skill <name> --tests <path> [--run-agent] [--generate]
+selftune eval import         --dir <path> --skill <name> --output <path> [--match-strategy exact|fuzzy]
+selftune eval composability  --skill <name> [--window N] [--telemetry-log <path>]
+
+# Other commands
 selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
 selftune status
 selftune last
 selftune doctor
 selftune dashboard [--export] [--out FILE] [--serve]
-selftune ingest-codex
-selftune ingest-opencode
-selftune ingest-openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]
-selftune wrap-codex -- <codex args>
-selftune replay     [--since DATE] [--dry-run] [--force] [--verbose]
+selftune dashboard --serve [--port <port>]
 selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
-selftune cron setup [--dry-run] [--tz <timezone>]
+selftune cron setup [--dry-run]                         # auto-detect platform (cron/launchd/systemd)
+selftune cron setup --platform openclaw [--dry-run] [--tz <timezone>]  # OpenClaw-specific
 selftune cron list
 selftune cron remove [--dry-run]
-selftune dashboard --serve [--port <port>]
-selftune evolve-body --skill <name> --skill-path <path> --target <routing_table|full_body> [--dry-run]
-selftune baseline   --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]
-selftune unit-test  --skill <name> --tests <path> [--run-agent] [--generate]
-selftune composability --skill <name> [--window N] [--telemetry-log <path>]
-selftune import-skillsbench --dir <path> --skill <name> --output <path> [--match-strategy exact|fuzzy]
 ```
 
 ## Workflow Routing
 
 | Trigger keywords | Workflow | File |
 |------------------|----------|------|
-| grade, score, evaluate, assess session | Grade | Workflows/Grade.md |
-| evals, eval set, undertriggering, skill stats | Evals | Workflows/Evals.md |
-| evolve, improve, triggers, catch more queries | Evolve | Workflows/Evolve.md |
-| rollback, undo, restore, revert evolution | Rollback | Workflows/Rollback.md |
-| watch, monitor, regression, post-deploy, performing | Watch | Workflows/Watch.md |
-| doctor, health, hooks, broken, diagnose | Doctor | Workflows/Doctor.md |
-| ingest, import, codex logs, opencode, openclaw, wrap codex | Ingest | Workflows/Ingest.md |
-| replay, backfill, claude transcripts, historical sessions | Replay | Workflows/Replay.md |
-| contribute, share, community, export data, anonymized | Contribute | Workflows/Contribute.md |
-| init, setup, bootstrap, first time | Initialize | Workflows/Initialize.md |
-| cron, schedule, autonomous, automate evolution | Cron | Workflows/Cron.md |
+| grade, score, evaluate, assess session, auto-grade | Grade † | Workflows/Grade.md |
+| evals, eval set, undertriggering, skill stats, eval generate | Evals | Workflows/Evals.md |
+| evolve, improve, optimize skills, make skills better, triggers, catch more queries | Evolve † | Workflows/Evolve.md |
+| evolve rollback, undo, restore, revert evolution, go back, undo last change | Rollback | Workflows/Rollback.md |
+| watch, monitor, regression, post-deploy, performing, keep an eye on | Watch † | Workflows/Watch.md |
+| doctor, health, hooks, broken, diagnose, not working, something wrong | Doctor | Workflows/Doctor.md |
+| ingest, import, codex logs, opencode, openclaw, wrap codex, ingest claude | Ingest † | Workflows/Ingest.md |
+| ingest claude, backfill, claude transcripts, historical sessions | Replay | Workflows/Replay.md |
+| contribute, share, community, export data, anonymized, give back, help others | Contribute | Workflows/Contribute.md |
+| init, setup, set up, bootstrap, first time, install, configure selftune | Initialize | Workflows/Initialize.md |
+| cron, schedule, autonomous, automate evolution, run automatically, run on its own | Cron | Workflows/Cron.md |
 | auto-activate, suggestions, activation rules, nag, why suggest | AutoActivation | Workflows/AutoActivation.md |
-| dashboard, visual, open dashboard, skill grid, serve dashboard, live dashboard | Dashboard | Workflows/Dashboard.md |
+| dashboard, visual, open dashboard, show dashboard, skill grid, serve dashboard, live dashboard | Dashboard | Workflows/Dashboard.md |
 | evolution memory, context memory, session continuity, what happened last | EvolutionMemory | Workflows/EvolutionMemory.md |
 | evolve body, evolve routing, full body evolution, rewrite skill, teacher student | EvolveBody | Workflows/EvolveBody.md |
-| baseline, baseline lift, adds value, skill value, no-skill comparison | Baseline | Workflows/Baseline.md |
-| unit test, skill test, test skill, generate tests, run tests, assertions | UnitTest | Workflows/UnitTest.md |
-| composability, co-occurrence, skill conflicts, skills together, conflict score | Composability | Workflows/Composability.md |
-| import skillsbench, skillsbench, external evals, benchmark tasks, import corpus | ImportSkillsBench | Workflows/ImportSkillsBench.md |
-| status, health summary, skill health, pass rates, how are skills | Status | *(direct command — no workflow file)* |
-| last, last session, recent session, what happened | Last | *(direct command — no workflow file)* |
+| grade baseline, baseline lift, adds value, skill value, no-skill comparison | Baseline | Workflows/Baseline.md |
+| eval unit-test, skill test, test skill, generate tests, run tests, assertions | UnitTest | Workflows/UnitTest.md |
+| eval composability, co-occurrence, skill conflicts, skills together, conflict score | Composability | Workflows/Composability.md |
+| eval import, skillsbench, external evals, benchmark tasks, import corpus | ImportSkillsBench | Workflows/ImportSkillsBench.md |
+| status, health summary, skill health, pass rates, how are skills, skills working, skills doing, run selftune, start selftune | Status | *(direct command — no workflow file)* |
+| last, last session, recent session, what happened, what changed, what did selftune do | Last | *(direct command — no workflow file)* |
+
+Workflows marked with † also run autonomously via `selftune orchestrate` without user interaction.
 
 ## Interactive Configuration
 
@@ -124,25 +141,27 @@ not a mandatory gate.
 ### Workflows That Skip Pre-Flight
 
 These read-only or simple workflows run immediately without prompting:
-`status`, `last`, `doctor`, `dashboard`, `watch`, `rollback`, `grade`,
-`ingest-*`, `replay`, `contribute`, `cron`, `composability`, `unit-test`,
-`import-skillsbench`.
+`status`, `last`, `doctor`, `dashboard`, `watch`, `evolve rollback`,
+`grade auto`, `ingest *`, `contribute`, `cron`, `eval composability`,
+`eval unit-test`, `eval import`.
 
 ## The Feedback Loop
 
-```
-Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
+```text
+Observe --> Detect --> Diagnose --> Propose --> Validate --> Audit --> Deploy --> Watch --> Rollback
    |                                                                    |
    +--------------------------------------------------------------------+
 ```
 
 1. **Observe** -- Hooks capture every session (queries, triggers, metrics)
-2. **Detect** -- `evals` finds missed triggers across invocation types
-3. **Diagnose** -- `grade` evaluates session quality with evidence
-4. **Propose** -- `evolve` generates description improvements
+2. **Detect** -- `selftune eval generate` extracts missed-trigger patterns across invocation types
+3. **Diagnose** -- `selftune grade` evaluates session quality with evidence
+4. **Propose** -- `selftune evolve` generates description improvements
 5. **Validate** -- Evolution is tested against the eval set
-6. **Deploy** -- Updated description replaces the original (with backup)
-7. **Watch** -- `watch` monitors for regressions post-deploy
+6. **Audit** -- Persist proposal, evidence, and decision metadata for traceability
+7. **Deploy** -- Updated description replaces the original (with backup)
+8. **Watch** -- `selftune watch` monitors for regressions post-deploy
+9. **Rollback** -- `selftune evolve rollback` restores the previous version when regressions are detected
 
 ## Resource Index
 
@@ -163,7 +182,7 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
 | `Workflows/Ingest.md` | Import sessions from Codex, OpenCode, and OpenClaw |
 | `Workflows/Replay.md` | Backfill logs from Claude Code transcripts |
 | `Workflows/Contribute.md` | Export anonymized data for community contribution |
-| `Workflows/Cron.md` | Manage OpenClaw cron jobs for autonomous evolution |
+| `Workflows/Cron.md` | Scheduling & automation (cron/launchd/systemd/OpenClaw) |
 | `Workflows/AutoActivation.md` | Auto-activation hook behavior and rules |
 | `Workflows/Dashboard.md` | Dashboard modes: static, export, live server |
 | `Workflows/EvolutionMemory.md` | Evolution memory system for session continuity |
@@ -178,12 +197,12 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
 selftune provides focused agents for deeper analysis. These live in
 `.claude/agents/` and can be spawned as subagents for specialized tasks.
 
-| Trigger keywords | Agent | Purpose |
-|------------------|-------|---------|
-| diagnose, root cause, why failing, skill failure, debug performance | diagnosis-analyst | Deep-dive analysis of underperforming skills |
-| patterns, conflicts, cross-skill, overlap, trigger conflicts, optimize skills | pattern-analyst | Cross-skill pattern analysis and conflict detection |
-| review evolution, check proposal, safe to deploy, approve evolution | evolution-reviewer | Safety gate review of pending evolution proposals |
-| set up selftune, integrate, configure project, install selftune | integration-guide | Guided interactive setup for specific project types |
+| Trigger keywords | Agent | Purpose | When to spawn |
+|------------------|-------|---------|---------------|
+| diagnose, root cause, why failing, skill failure, debug performance | diagnosis-analyst | Deep-dive analysis of underperforming skills | After doctor finds persistent issues, grades are consistently low, or status shows CRITICAL/WARNING |
+| patterns, conflicts, cross-skill, overlap, trigger conflicts, optimize skills | pattern-analyst | Cross-skill pattern analysis and conflict detection | When user asks about cross-skill conflicts or composability scores indicate moderate-to-severe conflicts |
+| review evolution, check proposal, safe to deploy, approve evolution | evolution-reviewer | Safety gate review of pending evolution proposals | Before deploying an evolution in interactive mode, especially for high-stakes or low-confidence proposals |
+| set up selftune, integrate, configure project, install selftune | integration-guide | Guided interactive setup for specific project types | For complex project structures (monorepo, multi-skill, mixed agent platforms) |
 
 ## Examples
 
@@ -227,6 +246,18 @@ selftune provides focused agents for deeper analysis. These live in
 - "Which skills conflict with each other?"
 - "Analyze composability for the Research skill"
 - "Import SkillsBench tasks for my skill"
+- "Install selftune"
+- "Configure selftune for this project"
+- "Make my skills better"
+- "Optimize my skills"
+- "Are my skills working?"
+- "Show me the dashboard"
+- "What changed since last time?"
+- "What did selftune do?"
+- "Run selftune"
+- "Start selftune"
+- "Go back to the previous version"
+- "Undo the last change"
 
 ## Negative Examples
 

package/skill/Workflows/AutoActivation.md

@@ -40,7 +40,7 @@ Detection scans all hook entries in settings for any command containing
 | `post-session-diagnostic` | Suggest diagnostic review | >2 unmatched queries in current session | `selftune last` |
 | `grading-threshold-breach` | Suggest evolution | Session pass rate < 0.6 (60%) | `selftune evolve` |
 | `stale-evolution` | Suggest evolution | >7 days since last evolution AND pending false negatives exist | `selftune evolve` |
-| `regression-detected` | Suggest rollback | Watch snapshot shows `regression_detected: true` | `selftune rollback` |
+| `regression-detected` | Suggest rollback | Watch snapshot shows `regression_detected: true` | `selftune evolve rollback` |
 
 ### Rule Details
 
@@ -121,24 +121,25 @@ Delete or comment out the entry to disable all auto-activation suggestions.
 
 ## Common Patterns
 
-**"Stop suggesting commands"**
-> Remove the auto-activate hook from settings (see Disabling above).
-> Or wait -- each rule only fires once per session.
+**User wants to disable auto-suggestions**
+> Remove the auto-activate hook entry from `~/.claude/settings.json`
+> (see Disabling section above). Each rule fires at most once per session.
 
-**"Why am I seeing selftune suggestions?"**
-> The auto-activate hook detected an actionable condition. Check which
-> rule fired (the suggestion includes the command) and follow the advice.
+**User asks why selftune suggestions appear**
+> Explain that the auto-activate hook detected an actionable condition.
+> Parse the suggestion text to identify which rule fired and report the
+> recommended action.
 
-**"Suggestions aren't appearing"**
+**Suggestions are not appearing when expected**
 > Run `selftune doctor` to verify the hook is installed. Check that
 > `UserPromptSubmit` includes the auto-activate hook in settings.
 
-**"PAI is installed but I still see suggestions"**
-> Verify PAI's `skill-activation-prompt` hook is in settings. The
-> coexistence check scans for that specific command string.
+**PAI coexistence conflict**
+> Verify PAI's `skill-activation-prompt` hook is in `~/.claude/settings.json`.
+> If present, selftune skips all suggestions automatically. If the user
+> sees duplicates, one of the two hooks is misconfigured.
 
-**"I want custom activation logic"**
-> Create rules conforming to the `ActivationRule` interface. Rules must
-> be pure filesystem readers -- no network, no heavy imports. Add them
-> to the rules array in `activation-rules.ts` or reference a custom
-> rules file.
+**User wants custom activation rules**
+> Direct the user to `cli/selftune/activation-rules.ts`. New rules must
+> conform to the `ActivationRule` interface: pure filesystem readers with
+> no network calls or heavy imports.

package/skill/Workflows/Badge.md

@@ -1,5 +1,11 @@
 # Badge Command
 
+## When to Use
+
+When the user asks for a skill health badge for their README.
+
+## Overview
+
 Generate skill health badges for embedding in READMEs and documentation.
 
 ## Usage