selftune 0.2.22 → 0.2.24

package/skill/{Workflows → workflows}/Initialize.md

@@ -6,7 +6,7 @@ Bootstrap selftune for first-time use or after changing environments.
 
 - The user asks to set up selftune, configure selftune, or initialize selftune
 - The agent detects `~/.selftune/config.json` does not exist
-- The user has switched agent platforms (Claude Code, Codex, OpenCode)
+- The user has switched agent platforms (Claude Code, Codex, OpenCode, Pi)
 - The user wants to add hooks for additional platforms (multi-agent setup)
 
 ## Default Command
@@ -21,7 +21,7 @@ selftune init --no-alpha [--force]
 
 | Flag                      | Description                                                               | Default       |
 | ------------------------- | ------------------------------------------------------------------------- | ------------- |
-| `--agent <type>`          | Agent platform: `claude_code`, `codex`, `opencode`, `openclaw`            | Auto-detected |
+| `--agent <type>`          | Agent platform: `claude_code`, `codex`, `opencode`, `openclaw`, `pi`      | Auto-detected |
 | `--cli-path <path>`       | Override auto-detected CLI entry-point path                               | Auto-detected |
 | `--force`                 | Reinitialize even if config already exists                                | Off           |
 | `--no-sync`               | Skip historical transcript backfill during init                           | Sync on       |
@@ -89,9 +89,12 @@ which selftune
 If `selftune` is not on PATH, install it:
 
 ```bash
-npm install -g selftune
+npx skills add selftune-dev/selftune
 ```
 
+If you manage the CLI directly instead of using the skill installer, use
+`npm install -g selftune` or `bun add -g selftune`.
+
 ### 2. Check Existing Config
 
 ```bash
@@ -146,6 +149,7 @@ CLIs available. Run these checks:
 which codex 2>/dev/null && echo "codex available"
 which opencode 2>/dev/null && echo "opencode available"
 ls ~/Documents/Cline/Hooks/ 2>/dev/null && echo "cline available"
+ls ~/.pi/agent/ 2>/dev/null && echo "pi available"
 ```
 
 If **any** additional platforms are detected, use `AskUserQuestion` listing only
@@ -168,9 +172,10 @@ For each platform the user selects, run the install command:
 selftune codex install      # writes hooks.json entries
 selftune opencode install   # writes shell shim + config entries
 selftune cline install      # creates hook scripts
+selftune pi install         # creates extension hook scripts
 ```
 
-Use `--dry-run` first if the user wants to preview. See `Workflows/PlatformHooks.md`
+Use `--dry-run` first if the user wants to preview. See `workflows/PlatformHooks.md`
 for platform-specific details.
 
 **Batch ingest** fallback for platforms without real-time hooks or to backfill history:
@@ -179,6 +184,7 @@ for platform-specific details.
 selftune ingest codex       # import Codex rollout sessions
 selftune ingest opencode    # import OpenCode sessions from SQLite
 selftune ingest openclaw    # import OpenClaw sessions
+selftune ingest pi          # import Pi sessions
 ```
 
 ### 5. Initialize Memory Directory
@@ -221,7 +227,7 @@ reported issues before proceeding.
 
 Init automatically runs `selftune sync` to backfill existing session
 transcripts into the SQLite database. This replays Claude Code transcripts,
-Codex rollouts, OpenCode sessions, and OpenClaw sessions so the eval set
+Codex rollouts, OpenCode sessions, OpenClaw sessions, and Pi sessions so the eval set
 and evolution pipeline have data to work with immediately.
 
 The sync step is fail-open — if it encounters errors, init continues.
@@ -412,8 +418,9 @@ retrying with `selftune init --alpha --alpha-email <email> --force`.
 
 **User asks to set up or initialize selftune**
 
-> Run `which selftune` to check installation. If missing, install with
-> `npm install -g selftune`. Run `selftune init`, then verify with
+> Run `which selftune` to check installation. If missing, install or refresh with
+> `npx skills add selftune-dev/selftune`. If the user manages the CLI directly,
+> use `npm install -g selftune` or `bun add -g selftune`. Run `selftune init`, then verify with
 > `selftune doctor`. Report results to the user.
 
 **User wants alpha enrollment**
@@ -426,8 +433,8 @@ retrying with `selftune init --alpha --alpha-email <email> --force`.
 
 > Run `selftune init` for the primary agent, then offer to install hooks for
 > additional detected platforms. Run `selftune codex install`, `selftune opencode install`,
-> or `selftune cline install` as needed. All platforms write to the same shared
-> log schema — no extra config required.
+> `selftune cline install`, or `selftune pi install` as needed. All platforms
+> write to the same shared log schema — no extra config required.
 
 **Hooks not capturing data**
 

package/skill/{Workflows → workflows}/Orchestrate.md

@@ -50,6 +50,7 @@ proposalModel = haiku
 | `--max-auto-grade <n>`      | Max ungraded skills to auto-grade per run (0 to disable)   | `5`        |
 | `--loop`                    | Run as a long-lived process that cycles continuously       | Off        |
 | `--loop-interval <seconds>` | Pause between cycles (minimum 60)                          | `3600`     |
+| `--help`                    | Show command help                                          | Off        |
 
 ## Default Behavior
 
@@ -57,7 +58,12 @@ proposalModel = haiku
 - Auto-grade up to 5 ungraded skills that have session data (enables evolution on first run after ingest)
 - Prioritize critical/warning/ungraded skills with real missed-query signal
 - Deploy validated low-risk description changes automatically
-- Watch recent deployments and roll back regressions automatically
+- Auto-grade and write grading baselines for freshly deployed skills
+- Generate review-first new skill proposals from strong workflow patterns
+- Watch recent deployments (including freshly deployed skills in same run) and roll back regressions automatically
+- Monitor grade regression alongside trigger regression during watch
+- Upload personal telemetry to cloud (alpha users)
+- Flush staged creator-directed contribution signals for opted-in skills
 
 Use `--review-required` only when you want a stricter policy for a specific run.
 
@@ -111,6 +117,7 @@ Machine-readable JSON with the summary fields plus a `decisions` array containin
 - `skill`, `action`, `reason`
 - `deployed`, `evolveReason`, `validation` (before/after pass rates, improved flag) — when evolved
 - `alert`, `rolledBack`, `passRate`, `recommendation` — when watched
+- `freshlyWatchedSkills` — array of skill names that were deployed and watched in the same run
 
 This is the recommended runtime for recurring autonomous scheduling.
 
@@ -162,8 +169,11 @@ In autonomous mode, orchestrate calls sub-workflows in this fixed order:
 2. **Status** — compute skill health using existing grade results (reads `grading.json` outputs from previous sessions)
 3. **Auto-grade** — grade up to `--max-auto-grade` (default 5) ungraded skills that have session data but no grades yet. Skipped during `--dry-run` (grading makes LLM calls). After grading, status is recomputed so candidate selection sees updated grades. Fail-open: individual grading errors are logged but never block the loop.
 4. **Evolve** — run evolution on selected candidates (pre-flight is skipped; Pareto mode uses 3 candidates; cheap-loop uses `haiku` for proposal + validation and `sonnet` for the final gate; adaptive gate escalation promotes risky proposals to `opus` + `high` effort; baseline and token-efficiency stay off)
-5. **Watch** — monitor recently evolved skills (auto-rollback enabled by default, `--recent-window` hours lookback)
-6. **Alpha Upload** — if enrolled in the alpha program (`config.alpha.enrolled === true`) and an API key is configured, stage new canonical records (sessions, invocations, evolution evidence, orchestrate runs) into `canonical_upload_staging`, build V2 push payloads, and flush to the cloud API (`POST /api/v1/push`) with Bearer auth. Fail-open: upload errors never block the orchestrate loop. Respects `--dry-run`.
+5. **Post-deploy grade + baseline** — for each freshly deployed skill, grade the most recent session and write a grading baseline to SQLite (`grading_baselines` table). The baseline records the measured pass rate and sample size, anchoring future grade regression detection. Fail-open: individual grading errors are logged but never block the loop.
+6. **Watch** — monitor recently evolved skills (auto-rollback enabled by default, `--recent-window` hours lookback). Skills freshly deployed in this run are included in the watch set immediately, so they are monitored in the same orchestrate cycle rather than waiting for the next run. These appear in `freshlyWatchedSkills` in the output. Grade watch (`enableGradeWatch: true`) runs alongside trigger regression for all watched skills.
+7. **Workflow proposals** — discover repeated multi-skill patterns and create review-first `new_skill` proposals when a workflow is strong enough to merit codification. These are never auto-deployed; they are surfaced as proposals for review.
+8. **Alpha Upload** — if enrolled in the alpha program (`config.alpha.enrolled === true`) and an API key is configured, stage new canonical records (sessions, invocations, evolution evidence, orchestrate runs) into `canonical_upload_staging`, build V2 push payloads, and flush to the cloud API (`POST /api/v1/push`) with Bearer auth. Fail-open: upload errors never block the orchestrate loop. Respects `--dry-run`.
+9. **Contribution relay flush** — if an API key is configured, flush any staged creator-directed contribution signals for opted-in skills. Fail-open: relay errors never block the orchestrate loop. Respects `--dry-run`.
 
 When orchestrate invokes evolve for a selected candidate, it always passes
 `confidenceThreshold: 0.6` and `maxIterations: 3`, plus the autonomous evolve

package/skill/{Workflows → workflows}/PlatformHooks.md

@@ -2,11 +2,11 @@
 
 ## Purpose
 
-Install and configure selftune hooks for non-Claude-Code platforms (Codex, OpenCode, Cline).
+Install and configure selftune hooks for non-Claude-Code platforms (Codex, OpenCode, Cline, Pi).
 
 ## When to Use
 
-- User wants selftune on Codex, OpenCode, or Cline
+- User wants selftune on Codex, OpenCode, Cline, or Pi
 - User asks about multi-platform support
 - User wants real-time skill tracking on a non-Claude-Code agent
 
@@ -18,7 +18,7 @@ Install and configure selftune hooks for non-Claude-Code platforms (Codex, OpenC
 selftune <platform> install [--dry-run] [--uninstall]
 ```
 
-Supported platforms: `codex`, `opencode`, `cline`
+Supported platforms: `codex`, `opencode`, `cline`, `pi`
 
 | Flag          | Description                                    |
 | ------------- | ---------------------------------------------- |
@@ -56,6 +56,13 @@ This is called automatically by the agent's hook system. Users don't run this di
 - Events: PostToolUse, TaskComplete, TaskCancel
 - Install creates executable shell scripts in the hooks directory
 
+### Pi
+
+- Config: `~/.pi/extensions/selftune/`
+- Sessions: `~/.pi/agent/sessions/`
+- Events: tool_call, tool_result, message, session_shutdown
+- Install creates executable hook scripts in the extensions directory
+
 ## Examples
 
 ### Codex
@@ -82,6 +89,14 @@ selftune cline install --dry-run    # Preview what would be created
 selftune cline install --uninstall  # Remove selftune hook scripts
 ```
 
+### Pi
+
+```bash
+selftune pi install              # Install hooks into ~/.pi/extensions/selftune/
+selftune pi install --dry-run    # Preview changes without writing
+selftune pi install --uninstall  # Remove selftune hooks
+```
+
 ### Hook handler (agent-only, not user-facing)
 
 The hook subcommand is called automatically by the agent. Users do not run it directly:
@@ -90,4 +105,5 @@ The hook subcommand is called automatically by the agent. Users do not run it di
 printf '%s\n' "$PAYLOAD" | selftune codex hook
 printf '%s\n' "$PAYLOAD" | selftune opencode hook
 printf '%s\n' "$PAYLOAD" | selftune cline hook
+printf '%s\n' "$PAYLOAD" | selftune pi hook
 ```

package/skill/workflows/Registry.md

@@ -0,0 +1,99 @@
+# Registry — Team Skill Distribution
+
+Manage versioned skill distribution across your team. Push skill folders to the cloud, install from the registry, sync to latest versions, and rollback when needed.
+
+## Commands
+
+| Command | Flags | What It Does |
+|---------|-------|-------------|
+| `selftune registry push [name]` | `--version=<semver>` `--summary=<text>` | Archive current skill folder and push as a new version |
+| `selftune registry install <name>` | `--global` | Download and extract a skill from the registry |
+| `selftune registry sync` | | Check all installed entries for updates, pull latest |
+| `selftune registry status` | | Show installed entries with version drift |
+| `selftune registry rollback <name>` | `--to=<version>` `--reason=<text>` | Rollback a skill to a previous version |
+| `selftune registry history <name>` | | Show version timeline with quality data |
+| `selftune registry list` | | Show all published entries in the org |
+
+## When to Use
+
+- User says "push this skill to the team" → `selftune registry push`
+- User says "install the deploy skill" → `selftune registry install deploy`
+- User says "update my skills" or "sync registry" → `selftune registry sync`
+- User says "check for updates" → `selftune registry status`
+- User says "rollback the deploy skill" → `selftune registry rollback deploy`
+- User says "show version history" → `selftune registry history <name>`
+- User says "what's in the registry" → `selftune registry list`
+
+## Push Workflow
+
+1. Navigate to the skill directory (must contain `SKILL.md`)
+2. Run `selftune registry push` — archives the entire folder (SKILL.md + scripts/ + assets/)
+3. The skill name and description are extracted from SKILL.md frontmatter
+4. Use `--version=1.0.0` for explicit semver, otherwise auto-generated
+5. Use `--summary="Added new trigger keywords"` for change notes
+
+## Install Workflow
+
+1. Run `selftune registry install <name>` to pull from the registry
+2. By default, installs to `.claude/skills/<name>/` in the current project
+3. Use `--global` to install to `~/.claude/skills/<name>/` (available everywhere)
+4. Installation is tracked — `selftune registry status` shows what's installed
+
+## Sync Workflow
+
+1. Run `selftune registry sync` to check all installations for updates
+2. Only downloads archives when the version hash differs (lightweight check)
+3. Local state is stored at `~/.selftune/registry-state.json`
+
+## Rollback Workflow
+
+1. Run `selftune registry rollback <name>` to revert to the previous version
+2. Use `--to=1.0.0` to target a specific version
+3. After rollback, tell team members to run `selftune registry sync`
+4. Rollback is recorded with timestamp and reason
+
+## Prerequisites
+
+- Must be authenticated (`selftune alpha upload` to set up API key)
+- Push and rollback require Team plan and admin role
+- Install requires Pro plan or higher
+
+## Output Format
+
+All commands output JSON for agent consumption:
+
+```json
+// push
+{"success": true, "name": "deploy", "version": "1.2.0", "files": 8, "size": 4096, "hash": "abc123"}
+
+// sync
+{"synced": 2, "failed": 0, "total": 5}
+
+// status
+{"installations": [{"name": "deploy", "installed": "1.1.0", "latest": "1.2.0", "status": "behind"}]}
+```
+
+## Common Patterns
+
+**User wants to share a skill with the team**
+
+> Run `selftune registry push` from the skill directory. Report the version
+> and file count from the JSON output.
+
+**User wants to install a shared skill**
+
+> Run `selftune registry install <name>`. Use `--global` if they want it
+> available across all projects.
+
+**User wants to check what's outdated**
+
+> Run `selftune registry status`. Report entries where `status` is `"behind"`.
+
+**User wants to update everything**
+
+> Run `selftune registry sync`. Report `synced` and `failed` counts.
+
+**User wants to undo a bad version**
+
+> Run `selftune registry rollback <name> --reason="regression in trigger accuracy"`.
+> Remind them to have team members run `selftune registry sync` afterward.

package/skill/{Workflows → workflows}/Schedule.md

@@ -4,7 +4,7 @@ Generate ready-to-use scheduling examples for automating selftune with
 standard system tools. This is the **primary automation path** — it works
 on any machine without requiring a specific agent runtime.
 
-For OpenClaw-specific scheduling, see `Workflows/Cron.md`.
+For OpenClaw-specific scheduling, see `workflows/Cron.md`.
 
 ## When to Use
 
@@ -51,7 +51,7 @@ Outputs examples for all three scheduling systems (cron, launchd, systemd).
 
 ## Alias
 
-`selftune schedule` is now an alias for `selftune cron`. Both commands are interchangeable. See `Workflows/Cron.md` for the full cron workflow reference.
+`selftune schedule` is now an alias for `selftune cron`. Both commands are interchangeable. See `workflows/Cron.md` for the full cron workflow reference.
 
 ## PATH Resolution (All Platforms)
 
@@ -69,4 +69,4 @@ environments that don't include homebrew, bun, or node binary locations.
 - **User wants quick setup on a Linux server** -- Run `selftune schedule --install --format cron`.
 - **User wants setup on macOS** -- Run `selftune schedule --install --format launchd`.
 - **User wants setup on a systemd-based server** -- Run `selftune schedule --install --format systemd`.
-- **User mentions OpenClaw** -- Use `selftune cron setup --platform openclaw` for the OpenClaw scheduler adapter. The default product path is still `selftune schedule --install`. See `Workflows/Cron.md`.
+- **User mentions OpenClaw** -- Use `selftune cron setup --platform openclaw` for the OpenClaw scheduler adapter. The default product path is still `selftune schedule --install`. See `workflows/Cron.md`.

package/skill/workflows/SignalsDashboard.md

@@ -0,0 +1,87 @@
+# selftune Signals Dashboard Workflow
+
+View contributor signals, contributor statistics, and skill signal strength
+from the hosted selftune cloud dashboard.
+
+This is **not** the same as:
+- `selftune dashboard` — the **local** SPA that reads your own SQLite telemetry
+- `selftune contribute` — exporting an anonymized **export bundle** for the community
+- `selftune contributions` — managing your **sharing preferences** for creator-directed signals
+- `selftune creator-contributions` — managing the **creator sharing setup** file (`selftune.contribute.json`)
+
+## When to Use
+
+- The user asks about contributor signals, contributor stats, or aggregated skill health
+- The user wants to see how many people are contributing signals for a skill
+- The user asks about signal performance, signal strength, or cohort counts
+- The user says "show me signals", "show me contributor signals", or "how are signals doing?"
+
+## Where to Find It
+
+The signals dashboard is the hosted web application at the selftune cloud
+URL (e.g. `https://selftune.dev/signals` or the locally-running Next.js
+dev server at `http://localhost:3000/signals`). The old `/community` path is a
+legacy alias.
+
+## What It Shows
+
+| Section | Description |
+| --- | --- |
+| Overview cards | Total contributors, total signals, active skills |
+| Skill list | Per-skill signal counts, distinct cohorts, trigger rates |
+| Signal strength | Whether a skill meets the actionable threshold (>=10 signals, >=3 cohorts) |
+| Time buckets | Signal volume over time |
+| Pending proposals | Skills eligible for contributor-signal-driven evolution proposals |
+| Below-threshold skills | Skills that need more data before proposals can be generated |
+
+## Signal Strength Thresholds
+
+A skill is considered **actionable** when it meets both of these thresholds:
+- At least **10 total signals** from contributors
+- At least **3 distinct contributor cohorts**
+
+Skills below these thresholds appear in the "needs more data" section.
+These same thresholds gate proposal generation on the API side.
+
+## Steps
+
+1. Direct the user to the signals dashboard URL
+2. If asked about a specific skill, describe its signal strength and contributor count
+3. If a skill is below threshold, explain how many more signals or cohorts are needed
+4. If the user wants to help a skill reach threshold, route to the **Contribute** workflow
+5. If the user is the skill creator, use the Community page as the handoff into proposals and watch
+
+## Creator Loop
+
+For a creator, the after-ship loop is:
+
+1. check whether the skill is low-signal or actionable
+2. inspect missed categories and grade distribution
+3. create a contributor proposal only when the signal is coherent
+4. review/apply the proposal through the normal proposal flow
+5. watch outcomes after apply
+
+Read `references/creator-playbook.md` for the full before-ship and after-ship playbook.
+
+## Common Patterns
+
+**User asks "how are contributor signals doing?"**
+
+> Direct them to the signals dashboard. Summarize the overview stats
+> (total contributors, total signals, number of actionable skills).
+
+**User asks about a specific skill's contributor signals**
+
+> Look up the skill on the signals dashboard. Report its total signals,
+> distinct cohorts, and whether it meets the actionable threshold.
+
+**User wants to help a skill that's below threshold**
+
+> Route to the Contribute workflow (`selftune contribute --skill <name>`)
+> to export an anonymized bundle and submit it.
+
+**User confuses signals dashboard with local dashboard**
+
+> Clarify: `selftune dashboard` shows **local** telemetry from your own
+> SQLite database. The signals dashboard shows **aggregated** data from
+> all contributors across the selftune cloud.

package/skill/{Workflows → workflows}/Sync.md

@@ -10,7 +10,7 @@ also writes the compatibility repaired overlay JSONL.
 ## When to Use
 
 - Before running `status`, `dashboard`, `watch`, or `evolve` when data may be stale
-- The user has run many Claude Code, Codex, OpenCode, or OpenClaw sessions since last sync
+- The user has run many Claude Code, Codex, OpenCode, OpenClaw, or Pi sessions since last sync
 - The agent detects host logs may be polluted and needs the repaired/source-first view
 - Before inspecting alpha-upload readiness or pushing fresh cloud data
 
@@ -31,6 +31,8 @@ selftune sync
 | `--no-codex`     | Skip Codex rollout ingest                       |
 | `--no-opencode`  | Skip OpenCode ingest                            |
 | `--no-openclaw`  | Skip OpenClaw ingest                            |
+| `--no-pi`        | Skip Pi ingest                                  |
+| `--pi-sessions-dir <dir>` | Pi sessions directory (default: `~/.pi/agent/sessions`) |
 | `--no-repair`    | Skip rebuilding repaired skill-usage data       |
 | `--json`         | Output results as JSON                          |
 

package/skill/{Workflows → workflows}/UnitTest.md

@@ -9,6 +9,14 @@ accuracy, output content, and tool usage with deterministic assertions.
 selftune eval unit-test --skill <name> --tests <path> [options]
 ```
 
+## Where selftune stores the result
+
+- Test definitions live in `~/.selftune/unit-tests/<skill>.json`
+- The latest run summary is mirrored into `~/.selftune/unit-tests/<skill>.last-run.json`
+
+The dashboard and `selftune status` read those files to decide whether a skill still needs test
+generation or already has a passing suite.
+
 ## Options
 
 | Flag                  | Description                                           | Default                               |
@@ -138,6 +146,17 @@ selftune eval unit-test --skill Research
 Compare the new `pass_rate` against the previous run. Report whether
 the evolution improved trigger accuracy.
 
+### 5. Continue the creator loop
+
+After unit tests exist, the next creator step is usually:
+
+```bash
+selftune evolve --skill <name> --skill-path <path> --dry-run --validation-mode replay
+```
+
+That keeps the sequence aligned with the dashboard readiness surface:
+evals -> unit tests -> replay dry-run -> baseline -> deploy -> watch.
+
 ## Common Patterns
 
 **User asks to generate tests for a skill**

package/skill/{Workflows → workflows}/Watch.md

@@ -20,6 +20,9 @@ selftune watch --skill <name> --skill-path <path> [options]
 | `--auto-rollback`     | Automatically rollback on detected regression    | Off      |
 | `--sync-first`        | Refresh source-truth telemetry before evaluating | Off      |
 | `--sync-force`        | Force a full source rescan during `--sync-first` | Off      |
+| `--grade-threshold <n>` | Grade regression threshold (drop from baseline)| 0.15     |
+| `--no-grade-watch`      | Disable grade-based regression monitoring        | Enabled  |
+| `--help`                | Show command help                               | Off      |
 
 ## Output Format
 
@@ -34,7 +37,22 @@ selftune watch --skill <name> --skill-path <path> [options]
   "regression_detected": false,
   "delta": -0.03,
   "status": "healthy",
-  "evaluated_at": "2026-02-28T14:00:00Z"
+  "evaluated_at": "2026-02-28T14:00:00Z",
+  "gradeAlert": null,
+  "gradeRegression": null
+}
+```
+
+When grade regression is detected, the additional fields are populated:
+
+```json
+{
+  "gradeAlert": "grade regression detected for \"pptx\": baseline_grade_pass_rate=0.85, recent_avg=0.65, delta=0.20 exceeds threshold=0.15",
+  "gradeRegression": {
+    "before": 0.85,
+    "after": 0.65,
+    "delta": 0.20
+  }
 }
 ```
 
@@ -47,6 +65,28 @@ selftune watch --skill <name> --skill-path <path> [options]
 | `regression`        | Pass rate dropped below baseline minus threshold  |
 | `insufficient_data` | Not enough sessions in the window to evaluate     |
 
+## Grade Regression Monitoring
+
+In addition to trigger-based regression (pass rate from eval sets), watch now
+monitors **grade regression** using grading baselines stored in SQLite.
+
+Grade regression compares the baseline grade pass rate (written when a skill is
+deployed) against the average pass rate of recent grading results. If the delta
+exceeds `gradeRegressionThreshold` (default 0.15), a `gradeAlert` is raised.
+
+This runs alongside trigger regression:
+
+| Check              | Source                      | Threshold | Field               |
+| ------------------ | --------------------------- | --------- | ------------------- |
+| Trigger regression | Eval set pass rates         | 0.10      | `regression_detected` |
+| Grade regression   | Grading baseline vs recent  | 0.15      | `gradeRegression`     |
+
+Both checks contribute to the overall `alert` field. A grade regression alert
+is appended to the watch alert string alongside any trigger regression alert.
+
+Grade watch is enabled by default. Disable it by passing `--no-grade-watch`
+if you only want trigger-based monitoring.
+
 ## Parsing Instructions
 
 ### Check Regression Status
@@ -105,7 +145,7 @@ If regression is detected:
 
 - Review recent session transcripts to understand what changed
 - Check if the eval set is still representative
-- Run `evolve rollback` if the regression is confirmed (see `Workflows/Rollback.md`)
+- Run `evolve rollback` if the regression is confirmed (see `workflows/Rollback.md`)
 
 If `--auto-rollback` was set, the command automatically restores the
 previous description and logs a `rolled_back` entry.

package/skill/{Workflows → workflows}/Workflows.md

@@ -6,14 +6,16 @@ When the user asks about multi-skill workflows, workflow discovery, or skill com
 
 ## Overview
 
-Discover repeated multi-skill sequences from telemetry and optionally save a
-discovered workflow into a skill's `## Workflows` section.
+Discover repeated multi-skill sequences from telemetry, save a discovered
+workflow into a skill's `## Workflows` section, or scaffold a new local skill
+from an observed workflow pattern.
 
 ## Default Commands
 
 ```bash
 selftune workflows [options]
 selftune workflows save <workflow-id|index> [--skill-path <path>]
+selftune workflows scaffold <workflow-id|index> [--output-dir <path>] [--skill-name <name>] [--description <text>] [--write]
 ```
 
 ## Options
@@ -29,6 +31,13 @@ selftune workflows save <workflow-id|index> [--skill-path <path>]
   auto-detect the first skill's SKILL.md path across contributing sessions. If
   that skill maps to multiple SKILL.md files in those sessions, the command
   errors and you must pass `--skill-path` explicitly.
+- `--output-dir <path>`: Target registry directory for `scaffold`. Default:
+  the repo-root `.agents/skills` directory.
+- `--skill-name <name>`: Override the generated scaffolded skill name.
+- `--description <text>`: Override the generated scaffolded skill description.
+- `--write`: Persist the scaffolded draft skill to disk. Without this flag,
+  `scaffold` previews the draft only.
+- `--force`: Overwrite an existing draft skill path when combined with `--write`.
 
 ## Save Semantics
 
@@ -49,6 +58,30 @@ SKILL.md. The subsection name is derived from the skill chain
 (`Copywriting-MarketingAutomation-SelfTuneBlog`) and includes
 discovered-source metadata with occurrence count and synergy score.
 
+## Scaffold Semantics
+
+`scaffold` turns an observed workflow into a draft local skill.
+
+- Default behavior is preview-first: the command prints the proposed skill name,
+  output path, provenance, and full `SKILL.md` content.
+- Add `--write` to create `<output-dir>/<skill-name>/SKILL.md`.
+- The generated skill is intentionally conservative: it includes provenance,
+  a description derived from the workflow trigger, an execution plan, and the
+  discovered workflow section. It does not silently publish or distribute the
+  new skill.
+
+When `selftune orchestrate` sees a strong workflow pattern, it now creates a
+review-first `new_skill` proposal automatically. The manual `scaffold` command
+still exists for explicit previewing and local draft writes.
+
+Examples:
+
+```bash
+selftune workflows scaffold 1
+selftune workflows scaffold "Copywriting→MarketingAutomation→SelfTuneBlog" --skill-name "blog publisher"
+selftune workflows scaffold 1 --output-dir .agents/skills --write
+```
+
 ## Output Format
 
 ### Human-readable output
@@ -127,3 +160,7 @@ Discovered Workflows (from 450 sessions):
   `selftune workflows save 1 --skill-path /path/to/SKILL.md`
 - "Save a specific discovered workflow by ID"  
   `selftune workflows save "Copywriting→MarketingAutomation→SelfTuneBlog"`
+- "Preview a new skill scaffold from the top workflow"  
+  `selftune workflows scaffold 1`
+- "Write the scaffolded draft skill into the repo registry"  
+  `selftune workflows scaffold 1 --output-dir .agents/skills --write`