selftune 0.1.0 → 0.1.4

package/package.json

@@ -1,16 +1,45 @@
 {
   "name": "selftune",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Skill observability and continuous improvement CLI for agent platforms",
   "type": "module",
-  "author": "Daniel Petro",
   "license": "MIT",
+  "author": "Daniel Petro",
+  "homepage": "https://github.com/WellDunDun/selftune#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WellDunDun/selftune.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WellDunDun/selftune/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/WellDunDun"
+  },
+  "keywords": [
+    "selftune",
+    "skill",
+    "observability",
+    "claude-code",
+    "codex",
+    "opencode",
+    "eval",
+    "grading",
+    "evolution",
+    "cli",
+    "agent",
+    "telemetry",
+    "bun",
+    "typescript"
+  ],
   "bin": {
     "selftune": "bin/selftune.cjs"
   },
   "files": [
     "bin/",
     "cli/selftune/",
+    "dashboard/",
     "skill/",
     "README.md",
     "CHANGELOG.md"
@@ -23,7 +52,7 @@
     "check": "bun run lint && bun run lint:arch && bun test"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.4.4",
     "@types/bun": "^1.1.0"
   }
 }

package/skill/SKILL.md

@@ -3,7 +3,8 @@ name: selftune
 description: >
   Skill observability and continuous improvement. Use when the user wants to:
   grade a session, generate evals, check undertriggering, evolve a skill
-  description, rollback an evolution, monitor post-deploy performance, run
+  description, rollback an evolution, monitor post-deploy performance, check
+  skill health status, view last session insight, open the dashboard, run
   health checks, or ingest sessions from Codex/OpenCode.
 ---
 
@@ -15,34 +16,31 @@ and evolve skill descriptions toward the language real users actually use.
 ## Bootstrap
 
 If `~/.selftune/config.json` does not exist, read `Workflows/Initialize.md`
-first. Do not proceed with other commands until initialization is complete.
+first. The CLI must be installed (`selftune` on PATH) before other commands
+will work. Do not proceed with other commands until initialization is complete.
 
 ## Command Execution Policy
 
-Build every CLI invocation from the config:
-
-```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH <command> [options]
-```
-
-Fallback (if config is missing or stale):
 ```bash
-bun run <repo-path>/cli/selftune/index.ts <command> [options]
+selftune <command> [options]
 ```
 
-All commands output deterministic JSON. Always parse JSON output -- never
-text-match against output strings.
+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.
 
 ## Quick Reference
 
 ```bash
-selftune grade    --skill <name> [--expectations "..."] [--use-agent]
+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>]
 selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
+selftune status
+selftune last
 selftune doctor
+selftune dashboard [--export] [--out FILE]
 selftune ingest-codex
 selftune ingest-opencode
 selftune wrap-codex -- <codex args>
@@ -60,6 +58,9 @@ selftune wrap-codex -- <codex args>
 | doctor, health, hooks, broken, diagnose | Doctor | Workflows/Doctor.md |
 | ingest, import, codex logs, opencode, wrap codex | Ingest | Workflows/Ingest.md |
 | init, setup, bootstrap, first time | Initialize | Workflows/Initialize.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)* |
+| dashboard, visual, open dashboard, skill grid | Dashboard | *(direct command — no workflow file)* |
 
 ## The Feedback Loop
 
@@ -106,6 +107,10 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
 - "Check selftune health"
 - "Ingest my codex logs"
 - "Show me skill stats"
+- "How are my skills performing?"
+- "What happened in my last session?"
+- "Open the selftune dashboard"
+- "Show skill health status"
 
 ## Negative Examples
 

package/skill/Workflows/Doctor.md

@@ -6,13 +6,7 @@ Reports pass/fail status for each check with actionable guidance.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH doctor
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts doctor
+selftune doctor
 ```
 
 ## Options
@@ -103,8 +97,7 @@ Doctor validates these areas:
 ### 1. Run Doctor
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH doctor
+selftune doctor
 ```
 
 ### 2. Check Results

package/skill/Workflows/Evals.md

@@ -7,13 +7,7 @@ its invocation type.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH evals --skill <name> [options]
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts evals --skill <name> [options]
+selftune evals --skill <name> [options]
 ```
 
 ## Options
@@ -104,8 +98,7 @@ bun run <repo-path>/cli/selftune/index.ts evals --skill <name> [options]
 Discover which skills have telemetry data and how many queries each has.
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH evals --list-skills
+selftune evals --list-skills
 ```
 
 Use this first to identify which skills have enough data for eval generation.
@@ -117,8 +110,7 @@ Cross-reference `skill_usage_log.jsonl` (positive triggers) against
 an eval set annotated with invocation types.
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH evals --skill pptx --max 50 --out evals-pptx.json
+selftune evals --skill pptx --max 50 --out evals-pptx.json
 ```
 
 The command:
@@ -135,15 +127,14 @@ View aggregate telemetry for a skill: average turns, tool call breakdown,
 error rates, and common bash command patterns.
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH evals --skill pptx --stats
+selftune evals --skill pptx --stats
 ```
 
 ## Steps
 
 ### 1. List Available Skills
 
-Run `--list-skills` to see what skills have telemetry data. If the target
+Run `selftune evals --list-skills` to see what skills have telemetry data. If the target
 skill has zero or very few queries, more sessions are needed before
 eval generation is useful.
 
@@ -179,15 +170,15 @@ beyond trigger coverage.
 ## Common Patterns
 
 **"What skills are undertriggering?"**
-> Run `--list-skills`, then for each skill with significant query counts,
+> Run `selftune evals --list-skills`, then for each skill with significant query counts,
 > generate evals and check for missed implicit/contextual queries.
 
 **"Generate evals for pptx"**
-> Run `evals --skill pptx`. Review the invocation type distribution.
+> Run `selftune evals --skill pptx`. Review the invocation type distribution.
 > Feed the output to `evolve` if coverage gaps exist.
 
 **"Show me skill stats"**
-> Run `evals --skill <name> --stats` for aggregate telemetry.
+> Run `selftune evals --skill <name> --stats` for aggregate telemetry.
 
 **"I want reproducible evals"**
 > Use `--seed <n>` to fix the random sampling of negative examples.

package/skill/Workflows/Evolve.md

@@ -7,13 +7,7 @@ natural-language queries without breaking existing triggers.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH evolve --skill <name> --skill-path <path> [options]
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts evolve --skill <name> --skill-path <path> [options]
+selftune evolve --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -23,8 +17,7 @@ bun run <repo-path>/cli/selftune/index.ts evolve --skill <name> --skill-path <pa
 | `--skill <name>` | Skill name | Required |
 | `--skill-path <path>` | Path to the skill's SKILL.md | Required |
 | `--eval-set <path>` | Pre-built eval set JSON | Auto-generated from logs |
-| `--mode api\|agent` | LLM mode for proposal generation | `agent` |
-| `--agent <name>` | Agent CLI binary to use | Auto-detected |
+| `--agent <name>` | Agent CLI to use (claude, codex, opencode) | Auto-detected |
 | `--dry-run` | Propose and validate without deploying | Off |
 | `--confidence <n>` | Minimum confidence threshold (0-1) | 0.7 |
 | `--max-iterations <n>` | Maximum retry iterations | 3 |
@@ -155,5 +148,6 @@ The evolution loop stops when any of these conditions is met (priority order):
 > Lower `--confidence` slightly or increase `--max-iterations`.
 > Also check if the eval set has contradictory expectations.
 
-**"I want to use the API directly"**
-> Pass `--mode api`. Requires `ANTHROPIC_API_KEY` in the environment.
+**"Which agent is being used?"**
+> The evolve command auto-detects your installed agent CLI.
+> Use `--agent <name>` to override (claude, codex, opencode).

package/skill/Workflows/Grade.md

@@ -6,13 +6,7 @@ with a 3-tier evaluation covering trigger, process, and quality.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH grade --skill <name> [options]
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts grade --skill <name> [options]
+selftune grade --skill <name> [options]
 ```
 
 ## Options
@@ -23,7 +17,7 @@ bun run <repo-path>/cli/selftune/index.ts grade --skill <name> [options]
 | `--expectations "..."` | Explicit expectations (semicolon-separated) | Auto-derived |
 | `--evals-json <path>` | Pre-built eval set JSON file | None |
 | `--eval-id <n>` | Specific eval ID to grade from the eval set | None |
-| `--use-agent` | Grade via agent subprocess (no API key needed) | Off (uses API) |
+| `--agent <name>` | Agent CLI to use (claude, codex, opencode) | Auto-detected |
 
 ## Output Format
 
@@ -153,5 +147,6 @@ Keep the summary concise. The full details are in `grading.json`.
 > Pass `--evals-json path/to/evals.json` and optionally `--eval-id N`
 > to grade a specific eval scenario.
 
-**"I don't have an API key"**
-> Use `--use-agent` to grade via agent subprocess instead of direct API.
+**"Which agent is being used?"**
+> The grader auto-detects your installed agent CLI (claude, codex, opencode).
+> Use `--agent <name>` to override the auto-detected agent.

package/skill/Workflows/Ingest.md

@@ -21,13 +21,7 @@ Batch ingest Codex rollout logs into the shared JSONL schema.
 ### Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH ingest-codex
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts ingest-codex
+selftune ingest-codex
 ```
 
 ### Options
@@ -48,9 +42,9 @@ Writes to:
 ### Steps
 
 1. Verify `$CODEX_HOME/sessions/` directory exists and contains session files
-2. Run `ingest-codex`
+2. Run `selftune ingest-codex`
 3. Verify entries were written by checking log file line counts
-4. Run `doctor` to confirm logs are healthy
+4. Run `selftune doctor` to confirm logs are healthy
 
 ---
 
@@ -61,13 +55,7 @@ Ingest OpenCode sessions from the SQLite database.
 ### Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH ingest-opencode
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts ingest-opencode
+selftune ingest-opencode
 ```
 
 ### Options
@@ -90,9 +78,9 @@ Writes to:
 ### Steps
 
 1. Verify the OpenCode database exists at the expected path
-2. Run `ingest-opencode`
+2. Run `selftune ingest-opencode`
 3. Verify entries were written by checking log file line counts
-4. Run `doctor` to confirm logs are healthy
+4. Run `selftune doctor` to confirm logs are healthy
 
 ---
 
@@ -104,13 +92,7 @@ that tees the JSONL stream while passing through to Codex.
 ### Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH wrap-codex -- <your codex args>
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts wrap-codex -- <your codex args>
+selftune wrap-codex -- <your codex args>
 ```
 
 ### Usage
@@ -118,7 +100,7 @@ bun run <repo-path>/cli/selftune/index.ts wrap-codex -- <your codex args>
 Everything after `--` is passed directly to `codex exec`:
 
 ```bash
-bun run $CLI_PATH wrap-codex -- --model o3 "Fix the failing tests"
+selftune wrap-codex -- --model o3 "Fix the failing tests"
 ```
 
 ### Output
@@ -135,25 +117,25 @@ stream for telemetry; it does not modify Codex behavior.
 1. Build the wrap-codex command with the desired Codex arguments
 2. Run the command (replaces `codex exec` in your workflow)
 3. Session telemetry is captured automatically
-4. Verify with `doctor` after first use
+4. Verify with `selftune doctor` after first use
 
 ---
 
 ## Common Patterns
 
 **"Ingest codex logs"**
-> Run `ingest-codex`. No options needed. Reads from `$CODEX_HOME/sessions/`.
+> Run `selftune ingest-codex`. No options needed. Reads from `$CODEX_HOME/sessions/`.
 
 **"Import opencode sessions"**
-> Run `ingest-opencode`. Reads from the SQLite database automatically.
+> Run `selftune ingest-opencode`. Reads from the SQLite database automatically.
 
 **"Run codex through selftune"**
-> Use `wrap-codex -- <codex args>` instead of `codex exec <args>` directly.
+> Use `selftune wrap-codex -- <codex args>` instead of `codex exec <args>` directly.
 
 **"Batch ingest vs real-time"**
-> Use `ingest-codex` or `ingest-opencode` for historical sessions.
-> Use `wrap-codex` for ongoing sessions. Both produce the same log format.
+> Use `selftune ingest-codex` or `selftune ingest-opencode` for historical sessions.
+> Use `selftune wrap-codex` for ongoing sessions. Both produce the same log format.
 
 **"How do I know it worked?"**
-> Run `doctor` after ingestion. Check that log files exist and are parseable.
-> Run `evals --list-skills` to see if the ingested sessions appear.
+> Run `selftune doctor` after ingestion. Check that log files exist and are parseable.
+> Run `selftune evals --list-skills` to see if the ingested sessions appear.

package/skill/Workflows/Initialize.md

@@ -6,19 +6,12 @@ Bootstrap selftune for first-time use or after changing environments.
 
 - First time using selftune in a new environment
 - After switching agent platforms (Claude Code, Codex, OpenCode)
-- After reinstalling or moving the selftune repository
 - When `~/.selftune/config.json` does not exist
 
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH init [--agent <type>] [--cli-path <path>] [--llm-mode agent|api]
-```
-
-Fallback (if config does not exist yet):
-```bash
-bun run <repo-path>/cli/selftune/index.ts init [options]
+selftune init [--agent <type>] [--cli-path <path>] [--force]
 ```
 
 ## Options
@@ -26,8 +19,8 @@ bun run <repo-path>/cli/selftune/index.ts init [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--agent <type>` | Agent platform: `claude`, `codex`, `opencode` | Auto-detected |
-| `--cli-path <path>` | Absolute path to `cli/selftune/index.ts` | Derived from repo location |
-| `--llm-mode <mode>` | `agent` (use agent subprocess) or `api` (use Anthropic API directly) | `agent` |
+| `--cli-path <path>` | Override auto-detected CLI entry-point path | Auto-detected |
+| `--force` | Reinitialize even if config already exists | Off |
 
 ## Output Format
 
@@ -57,7 +50,19 @@ Creates `~/.selftune/config.json`:
 
 ## Steps
 
-### 1. Check Existing Config
+### 1. Check if CLI is installed
+
+```bash
+which selftune
+```
+
+If `selftune` is not on PATH, install it:
+
+```bash
+npm install -g selftune
+```
+
+### 2. Check Existing Config
 
 ```bash
 cat ~/.selftune/config.json 2>/dev/null
@@ -66,18 +71,17 @@ cat ~/.selftune/config.json 2>/dev/null
 If the file exists and is valid JSON, selftune is already initialized.
 Skip to Step 5 (verify with doctor) unless the user wants to reinitialize.
 
-### 2. Run Init
+### 3. Run Init
 
 ```bash
-bun run /path/to/cli/selftune/index.ts init --agent claude --cli-path /path/to/cli/selftune/index.ts
+selftune init
 ```
 
-Replace paths with the actual selftune repository location.
+### 4. Install Hooks (Claude Code)
 
-### 3. Install Hooks (Claude Code)
-
-For Claude Code agents, merge the hooks from `skill/settings_snippet.json`
-into `~/.claude/settings.json`. Three hooks are required:
+If `init` reports hooks are not installed, merge the entries from
+`skill/settings_snippet.json` into `~/.claude/settings.json`. Three hooks
+are required:
 
 | Hook | Script | Purpose |
 |------|--------|---------|
@@ -85,23 +89,21 @@ into `~/.claude/settings.json`. Three hooks are required:
 | `PostToolUse` (Read) | `hooks/skill-eval.ts` | Track skill triggers |
 | `Stop` | `hooks/session-stop.ts` | Capture session telemetry |
 
-Replace `/PATH/TO/` in the snippet with the actual `cli/selftune/` directory.
-
-### 4. Platform-Specific Setup
+Derive the hook script paths from the `cli_path` field in `~/.selftune/config.json`.
+The hooks directory is at `dirname(cli_path)/hooks/`.
 
 **Codex agents:**
 - Use `wrap-codex` for real-time telemetry capture (see `Workflows/Ingest.md`)
-- Or batch-ingest existing sessions with `ingest-codex`
+- Or batch-ingest existing sessions with `selftune ingest-codex`
 
 **OpenCode agents:**
-- Use `ingest-opencode` to import sessions from the SQLite database
+- Use `selftune ingest-opencode` to import sessions from the SQLite database
 - See `Workflows/Ingest.md` for details
 
 ### 5. Verify with Doctor
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH doctor
+selftune doctor
 ```
 
 Parse the JSON output. All checks should pass. If any fail, address the
@@ -109,17 +111,13 @@ reported issues before proceeding.
 
 ## Common Patterns
 
-**"I just cloned the selftune repo"**
-> Run init with `--cli-path` pointing to the cloned `cli/selftune/index.ts`.
-> Then install hooks for your agent platform.
-
-**"I moved the repo to a new directory"**
-> Re-run init with the updated `--cli-path`. The config will be overwritten.
+**"Initialize selftune"**
+> Install the CLI (`npm install -g selftune`), run `selftune init`,
+> install hooks, and verify with `selftune doctor`.
 
 **"Hooks aren't capturing data"**
-> Run `doctor` to check hook installation. Verify paths in
+> Run `selftune doctor` to check hook installation. Verify paths in
 > `~/.claude/settings.json` point to actual files.
 
 **"Config exists but seems stale"**
-> Delete `~/.selftune/config.json` and re-run init, or run init with
-> `--cli-path` to update the path.
+> Run `selftune init --force` to reinitialize.

package/skill/Workflows/Rollback.md

@@ -6,13 +6,7 @@ Records the rollback in the evolution audit log for traceability.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH rollback --skill <name> --skill-path <path> [options]
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts rollback --skill <name> --skill-path <path> [options]
+selftune rollback --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -91,14 +85,13 @@ If `--proposal-id` is specified, use that instead.
 ### 2. Run Rollback
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH rollback --skill pptx --skill-path /path/to/SKILL.md
+selftune rollback --skill pptx --skill-path /path/to/SKILL.md
 ```
 
 Or to rollback a specific proposal:
 
 ```bash
-bun run $CLI_PATH rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
+selftune rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
 ```
 
 ### 3. Verify Restoration

package/skill/Workflows/Watch.md

@@ -6,13 +6,7 @@ pass rates against a baseline within a sliding window of recent sessions.
 ## Default Command
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH watch --skill <name> --skill-path <path> [options]
-```
-
-Fallback:
-```bash
-bun run <repo-path>/cli/selftune/index.ts watch --skill <name> --skill-path <path> [options]
+selftune watch --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -74,8 +68,7 @@ bun run <repo-path>/cli/selftune/index.ts watch --skill <name> --skill-path <pat
 ### 1. Run Watch
 
 ```bash
-CLI_PATH=$(cat ~/.selftune/config.json | jq -r .cli_path)
-bun run $CLI_PATH watch --skill pptx --skill-path /path/to/SKILL.md
+selftune watch --skill pptx --skill-path /path/to/SKILL.md
 ```
 
 ### 2. Check Regression Status