selftune 0.2.16 → 0.2.19

package/skill/Workflows/Hook.md

@@ -0,0 +1,131 @@
+# selftune Hook Workflow
+
+Manually invoke individual Claude Code hooks for debugging and testing.
+Each hook reads its payload from stdin and behaves exactly as it would when
+triggered by the Claude Code host agent.
+
+## When to Use
+
+- Debugging a specific hook's behavior with a known payload
+- The user says "hook", "run hook", "invoke hook", "manual hook", or "debug hook"
+- Testing hook installation by simulating a hook event
+- Verifying hook output before or after configuration changes
+
+## Default Command
+
+```bash
+echo '{"payload":"..."}' | selftune hook <name>
+```
+
+Where `<name>` is one of the 6 available hooks.
+
+## Available Hooks
+
+| Hook Name              | Claude Code Event      | Purpose                                                                 |
+| ---------------------- | ---------------------- | ----------------------------------------------------------------------- |
+| `prompt-log`           | UserPromptSubmit       | Logs every user query to SQLite for false-negative eval detection        |
+| `session-stop`         | Stop                   | Extracts session-level telemetry from transcript when a session ends     |
+| `skill-eval`           | PostToolUse            | Records skill usage when a SKILL.md is read or a Skill tool is invoked  |
+| `auto-activate`        | UserPromptSubmit       | Evaluates activation rules and suggests selftune actions via stderr      |
+| `skill-change-guard`   | PreToolUse             | Warns (advisory) when an agent is about to write to a SKILL.md file     |
+| `evolution-guard`      | PreToolUse             | Blocks writes to monitored SKILL.md files until `selftune watch` runs   |
+
+## Hook Details
+
+### prompt-log
+
+Fires on every user message before Claude processes it. Writes the query to
+SQLite so that `hooks-to-evals` can identify prompts that did NOT trigger a
+skill — the raw material for false-negative eval entries. Also writes a
+canonical prompt record.
+
+### session-stop
+
+Fires when a Claude Code session ends. Reads the session transcript JSONL and
+extracts process-level telemetry (tool calls, errors, skills triggered, token
+counts). Writes one record per session to SQLite with a JSONL backup. May
+trigger a reactive `selftune orchestrate` spawn if conditions are met.
+
+### skill-eval
+
+Fires after Read or Skill tool calls. If the target is a SKILL.md file or a
+Skill invocation, finds the triggering user query from the transcript and
+writes a usage record. Builds the real-usage eval dataset over time.
+
+### auto-activate
+
+Fires on every user message. Evaluates activation rules against the session
+context and outputs suggestions to stderr (shown to Claude as system messages).
+Suggestions are advisory only — exit code is always 0. Tracks session state to
+avoid repeated suggestions.
+
+### skill-change-guard
+
+Fires before Write/Edit tool calls. If the target is a SKILL.md file, outputs
+a suggestion to run `selftune watch --skill <name>` to monitor impact. Advisory
+only — exit code is always 0, never blocking. Uses session state to avoid
+repeating suggestions for the same skill.
+
+### evolution-guard
+
+Fires before Write/Edit tool calls. If the target is a SKILL.md file that has
+a deployed evolution under active monitoring, and no recent `selftune watch`
+snapshot exists, this hook BLOCKS the write with exit code 2. This prevents
+unmonitored changes to skills that are being tracked.
+
+Exit codes:
+
+- `0` — Allow (not a SKILL.md, not monitored, or watch is recent)
+- `2` — Block with message (Claude Code convention for PreToolUse hooks)
+
+Fail-open: any internal error results in exit 0 (never blocks accidentally).
+
+## Output Format
+
+Hook output varies by hook type:
+
+- **prompt-log, session-stop, skill-eval**: Write to SQLite and JSONL logs silently. Exit 0 on success.
+- **auto-activate**: Writes suggestions to stderr. Exit 0 always.
+- **skill-change-guard**: Writes advisory message to stderr. Exit 0 always.
+- **evolution-guard**: Writes block message to stderr on exit 2. Exit 0 when allowing.
+
+## Common Patterns
+
+**Debug a prompt-log hook**
+
+> Pipe a UserPromptSubmit payload to test prompt logging:
+>
+> ```bash
+> echo '{"session_id":"test","query":"improve my skills"}' | selftune hook prompt-log
+> ```
+
+**Test skill-eval with a PostToolUse payload**
+
+> ```bash
+> echo '{"tool_name":"Read","file_path":"/path/to/SKILL.md","session_id":"test"}' | selftune hook skill-eval
+> ```
+
+**Verify evolution-guard blocks correctly**
+
+> ```bash
+> echo '{"tool_name":"Write","file_path":"/path/to/monitored/SKILL.md"}' | selftune hook evolution-guard
+> echo $?  # Should be 2 if skill is monitored without recent watch
+> ```
+
+## Error Handling
+
+If no hook name is provided or the name is unrecognized, the command exits with
+a `UNKNOWN_COMMAND` error listing available hooks:
+
+```
+Unknown hook: (none). Available: prompt-log, session-stop, skill-eval, auto-activate, skill-change-guard, evolution-guard
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| "Unknown hook" error | Typo in hook name | Use one of: `prompt-log`, `session-stop`, `skill-eval`, `auto-activate`, `skill-change-guard`, `evolution-guard` |
+| Hook exits 0 but no data written | Payload missing required fields | Check the hook's expected payload schema in `cli/selftune/types.ts` |
+| evolution-guard always exits 0 | No deployed evolution for the target skill | Run `selftune evolve` first to deploy an evolution, then test the guard |
+| auto-activate produces no suggestions | Activation rules not configured or already suggested in session | Check `~/.selftune/` for activation rules and session state files |

package/skill/Workflows/Ingest.md

@@ -93,6 +93,13 @@ Writes to:
 - `~/.claude/all_queries_log.jsonl` -- extracted user queries
 - `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "codex_rollout"`
 
+### Notes
+
+- Conservative skill attribution: Codex rollout ingest only attributes a skill when it has
+  explicit evidence, such as a skill file/path read or an explicit user mention that invokes
+  the skill. Incidental mentions inside assistant reasoning, optimizer prompts, or eval text do
+  not count as triggers.
+
 ### Steps
 
 1. Verify `$CODEX_HOME/sessions/` directory exists and contains session files

package/skill/Workflows/Initialize.md

@@ -126,14 +126,15 @@ Code subagent calls stay up to date.
 
 **Hook reference** (for troubleshooting):
 
-| Hook                       | Script                        | Purpose                                         | Notes                                          |
-| -------------------------- | ----------------------------- | ----------------------------------------------- | ---------------------------------------------- |
-| `UserPromptSubmit`         | `hooks/prompt-log.ts`         | Log every user query                            | Accepts both `prompt` and legacy `user_prompt` |
-| `UserPromptSubmit`         | `hooks/auto-activate.ts`      | Suggest skills before prompt processing         | Uses `additionalContext` JSON for suggestions  |
-| `PreToolUse` (Write/Edit)  | `hooks/skill-change-guard.ts` | Detect uncontrolled skill edits                 | `if` filter: only fires on `*SKILL.md` paths   |
-| `PreToolUse` (Write/Edit)  | `hooks/evolution-guard.ts`    | Block SKILL.md edits on monitored skills        | `if` filter: only fires on `*SKILL.md` paths   |
-| `PostToolUse` (Read/Skill) | `hooks/skill-eval.ts`         | Track skill triggers and Skill tool invocations |                                                |
-| `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       | Runs async (non-blocking), 60s timeout         |
+| Hook                       | Script                        | Purpose                                         | Notes                                           |
+| -------------------------- | ----------------------------- | ----------------------------------------------- | ----------------------------------------------- |
+| `UserPromptSubmit`         | `hooks/prompt-log.ts`         | Log every user query                            | Accepts both `prompt` and legacy `user_prompt`  |
+| `UserPromptSubmit`         | `hooks/auto-activate.ts`      | Suggest skills before prompt processing         | Uses `additionalContext` JSON for suggestions   |
+| `PreToolUse` (Write/Edit)  | `hooks/skill-change-guard.ts` | Detect uncontrolled skill edits                 | `if` filter: only fires on `*SKILL.md` paths    |
+| `PreToolUse` (Write/Edit)  | `hooks/evolution-guard.ts`    | Block SKILL.md edits on monitored skills        | `if` filter: only fires on `*SKILL.md` paths    |
+| `PostToolUse` (Read/Skill) | `hooks/skill-eval.ts`         | Track skill triggers and Skill tool invocations | Fast-path: skips non-PostToolUse/non-Read/Skill |
+| `PostToolUse` (Bash)       | `hooks/commit-track.ts`       | Track git commits for session traceability      | Fast-path: skips non-git Bash commands          |
+| `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       | Runs async (non-blocking), 60s timeout          |
 
 **Codex agents:**
 
@@ -191,6 +192,25 @@ and evolution pipeline have data to work with immediately.
 The sync step is fail-open — if it encounters errors, init continues.
 Skip with `--no-sync` if you only want hooks for forward-looking data.
 
+If the user is migrating from a much older pre-SQLite install and wants to
+recover legacy selftune JSONL history itself, use `selftune recover` as a
+separate recovery step. That is not part of normal first-time setup.
+
+Recovery quick reference:
+
+| Flag | Description |
+| --- | --- |
+| `--full` | Rebuild SQLite from the available JSONL/export sources |
+| `--force` | Skip the SQLite-only preflight guard during a full rebuild |
+| `--since <date>` | Recover only rows on or after the given date |
+| `--json` | Output JSON summary instead of human-readable text |
+
+Example:
+
+```bash
+selftune recover --full --force
+```
+
 ### 9. Autonomy Scheduling
 
 Init automatically installs OS-level scheduling (launchd on macOS, cron/systemd
@@ -270,7 +290,7 @@ Enrollment uses a device-code flow — one command, one browser approval, fully
 
 ### Setup Sequence
 
-1. **Check local config**: Run `selftune status` — look for the "Alpha Upload" section
+1. **Check local config**: Run `selftune status` — use the first summary line and compact `Highlights` section to explain current skill health, then look for the "Alpha Upload" section
 2. **If not linked**: First use `AskUserQuestion` for the opt-in decision. Only if the user says yes, collect their email and run:
 
    ```bash

package/skill/Workflows/Orchestrate.md

@@ -20,6 +20,22 @@ recent changes with auto-rollback enabled.
 selftune orchestrate
 ```
 
+Autonomous evolve settings used by orchestrate:
+
+```text
+confidenceThreshold = 0.6
+maxIterations = 3
+paretoEnabled = true
+candidateCount = 3
+tokenEfficiencyEnabled = false
+withBaseline = false
+validationModel = haiku
+cheapLoop = true
+gateModel = sonnet
+adaptiveGate = true
+proposalModel = haiku
+```
+
 ## Flags
 
 | Flag                        | Description                                                | Default    |
@@ -109,10 +125,11 @@ This is the recommended runtime for recurring autonomous scheduling.
 | **Automated (loop)** | `selftune orchestrate --loop`         | No agent session; LLM cost only if evolution triggers | Configurable interval |
 
 In automated mode, the OS calls the CLI binary directly. No agent session
-is created. LLM calls only happen during the evolution step (proposing and
-validating description changes), which uses the configured model tier.
-The orchestrate logic itself (sync, status, candidate selection) is pure
-data processing with zero token cost.
+is created. Outside of the regular sync/status/candidate-selection logic,
+LLM calls can come from auto-grading ungraded skills and from the evolution
+step itself. By default, orchestrate runs proposal generation and validation
+on `haiku`, then re-runs the final gate on `sonnet` before deploy. Risky
+candidates are escalated to `opus` with `high` effort for the gate only.
 
 **Cron mode:** Install OS-level scheduling with `selftune cron setup`.
 Runs as separate invocations on a schedule (default: every 6 hours).
@@ -144,10 +161,15 @@ In autonomous mode, orchestrate calls sub-workflows in this fixed order:
 1. **Sync** — refresh source-truth telemetry across all supported agents (`selftune sync`)
 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, cheap-loop mode enabled, defaults used)
+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`.
 
+When orchestrate invokes evolve for a selected candidate, it always passes
+`confidenceThreshold: 0.6` and `maxIterations: 3`, plus the autonomous evolve
+defaults listed above. Those defaults are the recurring-run policy for the
+autonomy-first loop; there are no orchestrate flags to override them per run.
+
 Between candidate selection and evolution, orchestrate checks for
 **cross-skill eval set overlap**. When two or more evolution candidates
 share >30% of their positive eval queries, a warning is logged to stderr.

package/skill/Workflows/Quickstart.md

@@ -0,0 +1,94 @@
+# selftune Quickstart Workflow
+
+Guided onboarding that runs init, ingest, and status in a single command.
+Designed for first-time users who want to get selftune working immediately.
+
+## When to Use
+
+- The user is setting up selftune for the first time
+- The user says "getting started", "quickstart", "onboard", or "first time"
+- The agent needs to bootstrap selftune in one step without running init, ingest, and status separately
+
+## Default Command
+
+```bash
+selftune quickstart
+```
+
+Help:
+
+```bash
+selftune quickstart --help
+```
+
+## Options
+
+| Flag     | Description            |
+| -------- | ---------------------- |
+| `--help` | Show usage information |
+
+## Steps Performed
+
+Quickstart runs three steps automatically:
+
+1. **Init** — Creates `~/.selftune/config.json` if it does not exist. Skips if config is already present.
+2. **Ingest** — Runs Claude Code transcript replay if the ingest marker file does not exist. Discovers transcripts from `~/.claude/projects/` and writes session telemetry to SQLite.
+3. **Status** — Displays current skill health using `computeStatus`. Shows pass rates, trends, and health indicators for all detected skills; when you need per-skill check volume, look at `snapshot.skill_checks` rather than a "session count" field.
+
+After status, quickstart suggests the top 3 skills that would benefit from evolution, prioritized by:
+
+- **UNGRADED/UNKNOWN** skills (highest priority) — suggests running `selftune grade`
+- **CRITICAL** skills (pass rate below threshold) — suggests evolution
+- **WARNING** skills — suggests improvement
+
+## Output Format
+
+```text
+selftune quickstart
+====================
+
+[1/3] Config exists, skipping init.
+[2/3] Running ingest claude...
+      Ingested 12 sessions.
+[3/3] Current status:
+
+  Skill Health Summary
+  ...
+
+Suggested next steps:
+  - my-skill: pass rate 45% — needs evolution
+  - other-skill: needs grading — run `selftune grade --skill other-skill`
+```
+
+If all skills are healthy, the output ends with:
+
+```text
+All skills are healthy. No immediate actions needed.
+```
+
+## Common Patterns
+
+**First-time setup**
+
+> Run `selftune quickstart`. It handles init, ingest, and status automatically.
+
+**Already initialized**
+
+> Quickstart skips steps that are already complete (config exists, ingest marker exists). It is safe to run multiple times.
+
+**No transcripts found**
+
+> If no Claude Code transcripts exist in `~/.claude/projects/`, quickstart reports "No Claude Code transcripts found" and continues to the status step. The user should run some agent sessions first, then re-run quickstart.
+
+**Status or ingest fails**
+
+> Quickstart catches errors in each step and suggests the manual command for troubleshooting (e.g., `selftune init`, `selftune ingest claude`, or `selftune status`).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| "Init failed" at step 1 | Config directory permissions or corrupted config | Run `selftune init --force` manually |
+| "Ingest failed" at step 2 | Transcript directory missing or unreadable | Verify `~/.claude/projects/` exists and contains session directories |
+| "No sessions found" after ingest | No actionable transcripts or no skill usage detected | Run agent sessions that use skills, then re-run quickstart |
+| "Status failed" at step 3 | SQLite database issue | Run `selftune doctor` to diagnose |

package/skill/Workflows/Recover.md

@@ -0,0 +1,84 @@
+# selftune Recover Workflow
+
+Recover or backfill the local SQLite database from legacy JSONL files or an
+explicit `selftune export` snapshot.
+
+This is a recovery-only workflow. Normal operation should use `selftune sync`,
+which replays native source data into SQLite and also triggers alpha upload
+when enrolled.
+
+## When to Use
+
+- The user is migrating from a pre-SQLite selftune install and still has
+  legacy JSONL history that is not in SQLite yet
+- The user exported SQLite to JSONL and now needs to rebuild a fresh DB from
+  that snapshot
+- The user explicitly asks to recover, rebuild, or backfill SQLite from JSONL
+
+## Default Command
+
+```bash
+selftune recover
+```
+
+## Options
+
+| Flag                           | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `--full`                       | Rebuild SQLite tables from scratch                            |
+| `--force`                      | Skip the preflight guard for SQLite-only rows during rebuild  |
+| `--since <date>`               | Incrementally materialize records on/after this date          |
+| `--canonical-log <path>`       | Canonical JSONL path override                                 |
+| `--telemetry-log <path>`       | Session telemetry JSONL path override                         |
+| `--evolution-audit-log <path>` | Evolution audit JSONL path override                           |
+| `--evolution-evidence-log <path>` | Evolution evidence JSONL path override                     |
+| `--orchestrate-run-log <path>` | Orchestrate runs JSONL path override                          |
+| `--json`                       | Output a JSON summary                                         |
+
+## Output
+
+The command prints a summary of what was materialized into SQLite:
+
+- sessions
+- prompts
+- skill invocations
+- execution facts
+- session telemetry
+- legacy skill usage
+- evolution audit
+- evolution evidence
+- orchestrate runs
+
+With `--json`, the result includes `mode`, `source`, `since`, `force`, and the
+full count breakdown.
+
+## Common Patterns
+
+**Backfill legacy JSONL into an existing SQLite DB**
+
+> Run `selftune recover`.
+
+**Rebuild a deleted DB from an explicit export snapshot**
+
+> Run `selftune export --output ./recovery-snapshot`, then recover from the exported JSONL files explicitly:
+>
+> `selftune recover --full --force --telemetry-log ./recovery-snapshot/session_telemetry_log.jsonl --evolution-audit-log ./recovery-snapshot/evolution_audit_log.jsonl --evolution-evidence-log ./recovery-snapshot/evolution_evidence_log.jsonl --orchestrate-run-log ./recovery-snapshot/orchestrate_run_log.jsonl`
+
+**Recover only recent JSONL rows**
+
+> Run `selftune recover --since 2026-01-01`.
+
+## Important Notes
+
+- Do **not** use this as a normal freshness command. Use `selftune sync` for day-to-day operation.
+- Alpha upload remains SQLite-first. Recovery only repopulates SQLite so the normal upload pipeline can stage and send data afterward.
+- If you are recovering from post-cutover data, prefer a SQLite backup or `selftune export` snapshot. Passive legacy JSONL files do not contain all post-cutover records.
+
+## Example Flags Used Above
+
+| Flag | Description |
+| --- | --- |
+| `-o, --output <dir>` | Export SQLite into a portable snapshot directory |
+| `--full` | Rebuild SQLite tables from scratch |
+| `--force` | Skip the SQLite-only preflight guard during full rebuild |
+| `--telemetry-log <path>` | Point recover at the exported telemetry JSONL file |

package/skill/Workflows/RepairSkillUsage.md

@@ -0,0 +1,95 @@
+# selftune Repair Skill Usage Workflow
+
+Rebuild trustworthy skill-usage records by replaying Claude Code transcripts
+and Codex rollouts. Repairs the canonical SQLite `skill_invocations` table for
+historical legacy rows, and also writes a compatibility/export overlay
+(`skill_usage_repaired.jsonl`) that corrects missing or inaccurate skill paths,
+scopes, and query associations from the raw hook-captured data. The overlay is
+for compatibility/export only; SQLite is the operational source of truth.
+
+## When to Use
+
+- Skill usage data appears incomplete or has missing `skill_path` values
+- The user says "repair", "rebuild usage", "fix skill usage", or "trustworthy usage"
+- Before evolution or grading when hook data may be unreliable
+- After changing skill directory layouts or reinstalling skills
+
+## Default Command
+
+```bash
+selftune repair-skill-usage
+```
+
+## Options
+
+| Flag                        | Description                                              |
+| --------------------------- | -------------------------------------------------------- |
+| `--projects-dir <dir>`      | Claude transcript directory (default: `~/.claude/projects`) |
+| `--codex-home <dir>`        | Codex home directory (default: `~/.codex`)               |
+| `--since <date>`            | Only repair sessions modified on/after this date         |
+| `--out <path>`              | Repaired overlay log output path                         |
+| `--sessions-marker <path>`  | Repaired session-id marker file path                     |
+| `--skill-log <path>`        | Raw skill usage log path (for path lookup bootstrap)     |
+| `--dry-run`                 | Show summary counts without writing files                |
+| `--help`                    | Show usage information                                   |
+
+## How It Works
+
+1. **Discover transcripts** — Finds all Claude Code transcript JSONL files under `--projects-dir` and Codex rollout files under `--codex-home`.
+2. **Bootstrap path lookup** — Reads existing skill usage records from SQLite (or `--skill-log` JSONL) to build a skill-name-to-path lookup table.
+3. **Replay transcripts** — For each transcript, parses the conversation to find Skill tool invocations, associates them with the preceding user query, and resolves skill paths via installed-scope discovery or the lookup table.
+4. **Replay Codex rollouts** — Same process for Codex rollout files, using Codex-specific path resolution.
+5. **Repair SQLite + write overlay** — Replaces legacy triggered skill rows in SQLite when safe, inserts repaired canonical rows for legacy-only session/skill pairs, reconstructs contextual missed triggers from `Read .../SKILL.md` evidence, then writes deduplicated records to the repaired log and updates the session marker.
+
+## Output Format
+
+JSON summary printed to stdout:
+
+```json
+{
+  "transcripts_scanned": 42,
+  "codex_rollouts_scanned": 8,
+  "repaired_sessions": 35,
+  "repaired_records": 127,
+  "codex_repaired_records": 12,
+  "unique_matched_queries": 98,
+  "reins_queries_seen": 5,
+  "reins_skill_matches": 3,
+  "output": "~/.claude/skill_usage_repaired.jsonl"
+}
+```
+
+With `--dry-run`, the same summary is printed but no files are written.
+
+On non-dry runs, the JSON summary also includes a `sqlite` object with counts
+for deleted legacy rows, inserted repair rows, and skipped pairs that already
+had canonical data. Repaired rows can be either triggered invocations or
+contextual misses reconstructed from transcript reads of `SKILL.md`.
+
+## Common Patterns
+
+**Preview repair scope**
+
+> Run `selftune repair-skill-usage --dry-run` to see how many sessions and records would be repaired.
+
+**Repair only recent sessions**
+
+> Run `selftune repair-skill-usage --since 2025-01-01` to limit the repair to sessions from this year.
+
+**Full rebuild from scratch**
+
+> Run `selftune repair-skill-usage` without `--since` to rebuild the entire overlay from all available transcripts.
+> This also repairs SQLite-backed skill invocations for legacy-only historical rows.
+
+**Agent chaining into evolution**
+
+> Run repair before evolution to ensure skill usage data is accurate: `selftune repair-skill-usage && selftune evolve --skill my-skill`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `repaired_records: 0` | No Skill tool invocations found in transcripts | Verify skills are being invoked in sessions; check `selftune status` |
+| Many `(repaired:name)` paths | Skill not installed or path not discoverable | Install the skill or provide a `--skill-log` with known paths |
+| `transcripts_scanned: 0` | No transcripts in projects directory | Verify `~/.claude/projects/` contains session directories |
+| Invalid `--since` date error | Date format not parseable | Use ISO format: `--since 2025-01-15` |

package/skill/Workflows/Sync.md

@@ -1,15 +1,18 @@
 # selftune Sync Workflow
 
-Refresh source-truth telemetry across supported agent CLIs, then rebuild the
-repaired skill-usage overlay so status, dashboard, grading, and evolution work
-from real transcripts/rollouts instead of stale hook data.
+Refresh source-truth telemetry across supported agent CLIs into SQLite, then
+rebuild the repaired skill-usage layer so status, dashboard, grading, and
+evolution work from real transcripts/rollouts instead of stale hook data. The
+repair phase updates canonical SQLite skill invocations for legacy historical
+rows, reconstructs contextual misses from transcript `SKILL.md` reads, and
+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 agent detects host logs may be polluted and needs the repaired/source-first view
-- Before exporting data to cloud ingest
+- Before inspecting alpha-upload readiness or pushing fresh cloud data
 
 ## Default Command
 
@@ -22,24 +25,25 @@ selftune sync
 | Flag             | Description                                     |
 | ---------------- | ----------------------------------------------- |
 | `--since <date>` | Only sync sessions modified on/after this date  |
-| `--dry-run`      | Show summary without writing files              |
+| `--dry-run`      | Show summary without writing to SQLite or files |
 | `--force`        | Ignore per-source markers and rescan everything |
 | `--no-claude`    | Skip Claude transcript replay                   |
 | `--no-codex`     | Skip Codex rollout ingest                       |
 | `--no-opencode`  | Skip OpenCode ingest                            |
 | `--no-openclaw`  | Skip OpenClaw ingest                            |
-| `--no-repair`    | Skip rebuilding `skill_usage_repaired.jsonl`    |
+| `--no-repair`    | Skip rebuilding repaired skill-usage data       |
 | `--json`         | Output results as JSON                          |
 
 ## Output
 
 Writes/refreshed data:
 
-- `~/.claude/session_telemetry_log.jsonl`
-- `~/.claude/all_queries_log.jsonl`
-- `~/.claude/skill_usage_log.jsonl`
-- `~/.claude/skill_usage_repaired.jsonl`
+- SQLite operational tables in `~/.selftune/selftune.db`
+- canonical SQLite `skill_invocations` repair rows / legacy-row cleanup
+- `~/.claude/skill_usage_repaired.jsonl` compatibility/export overlay
+- local creator-directed contribution staging rows for approved skills
 - per-source marker files
+- alpha upload queue/staging activity when alpha is enrolled
 
 ## Steps
 
@@ -53,8 +57,10 @@ counts. Report the preview summary to the user.
 Run `selftune sync`. The output includes:
 
 - Per-source `scanned`, `synced`, and `skipped` counts
-- Repaired overlay totals
+- Repaired skill-usage totals
+- Creator-directed contribution staging totals when approved skills are installed
 - Any errors or warnings
+- Alpha upload summary when cloud upload is enabled
 
 ### 3. Verify Results
 
@@ -67,7 +73,7 @@ sync reports source/hook failures or expected active sources are missing.
 
 After sync completes, proceed with the user's intended workflow:
 `selftune status`, `selftune dashboard`, `selftune watch --sync-first`,
-or `selftune evolve --sync-first`.
+`selftune evolve --sync-first`, or `selftune alpha upload` for a manual upload.
 
 ## `--json` Usage