selftune 0.2.18 → 0.2.19

package/skill/Workflows/Contribute.md

@@ -1,8 +1,11 @@
 # selftune Contribute Workflow
 
-Export anonymized skill observability data as a JSON bundle for community
-contribution. Helps improve selftune's skill routing without exposing
-private data.
+Export anonymized skill observability data as a JSON bundle for **community**
+contribution. Helps improve selftune's skill routing without exposing private data.
+
+This is **not** the same as `selftune contributions`, which manages per-skill
+creator-directed sharing preferences, or `selftune creator-contributions`,
+which manages the creator-side bundled config file.
 
 ## When to Use
 

package/skill/Workflows/Contributions.md

@@ -0,0 +1,97 @@
+# selftune Contributions Workflow
+
+Manage local preferences for future creator-directed contribution flows.
+
+This is **not** the same as `selftune contribute`:
+- `selftune contributions` manages per-skill opt-in choices for creator-directed sharing
+- `selftune contribute` exports a community contribution bundle
+- `selftune creator-contributions` manages the creator-side `selftune.contribute.json` file
+
+## When to Use
+
+- The user asks to approve or revoke sharing signals with a specific skill creator
+- The user wants to see which creator-directed contribution preferences are stored locally
+- The user wants to set a default behavior for future creator-directed contribution prompts
+
+## Default Commands
+
+```bash
+selftune contributions
+selftune contributions preview <skill>
+selftune contributions approve <skill>
+selftune contributions revoke <skill>
+selftune contributions default <ask|always|never>
+selftune contributions upload [--dry-run] [--retry-failed] [--limit <n>]
+```
+
+## What It Does Today
+
+- Discovers installed skills that ship a `selftune.contribute.json` config
+- Stores local opt-in / opt-out state in `~/.selftune/contribution-preferences.json`
+- Stages privacy-safe creator-directed relay signals locally during `selftune sync` once a skill is approved
+- Keeps creator-directed sharing preferences separate from:
+  - `selftune contribute` community export bundles
+  - `selftune alpha upload` personal cloud uploads
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `selftune contributions` | Show current creator-directed contribution preferences |
+| `selftune contributions status` | Same as above |
+| `selftune contributions preview <skill>` | Show the privacy-safe relay payload shape for one skill |
+| `selftune contributions approve <skill>` | Approve creator-directed sharing for one skill |
+| `selftune contributions revoke <skill>` | Revoke creator-directed sharing for one skill |
+| `selftune contributions default <ask|always|never>` | Set the default behavior for future creator-directed prompts |
+| `selftune contributions upload [--dry-run] [--retry-failed] [--limit <n>]` | Flush locally staged creator-directed relay signals |
+| `selftune contributions reset` | Reset all creator-directed sharing preferences to defaults |
+
+## Upload Flags
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `--dry-run` | Boolean | Show pending staged rows without uploading |
+| `--retry-failed` | Boolean | Requeue failed rows before attempting upload |
+| `--limit <n>` | Integer | Maximum number of staged rows to upload in one run |
+
+## Notes
+
+- This workflow now shows which installed skills are requesting creator-directed sharing via `selftune.contribute.json`.
+- Once approved, creator-directed contribution signals are staged locally during `selftune sync` / `selftune orchestrate`.
+- Use `selftune contributions upload` to flush staged rows to the creator-directed relay endpoint.
+- Relay upload is separate from `selftune alpha upload` and currently reuses the local cloud API key when available.
+- Use `selftune contribute` when the user explicitly wants to export/share an anonymized community bundle.
+- Use `selftune alpha upload` when the user wants to push their own cloud telemetry.
+
+## Common Patterns
+
+**User asks what creator-directed sharing is configured**
+
+> Run `selftune contributions` and summarize the global default plus any per-skill choices.
+
+**User wants to allow contribution signals for one skill**
+
+> Run `selftune contributions approve <skill>`.
+
+**User wants to see what would actually be shared**
+
+> Run `selftune contributions preview <skill>` and summarize the requested signals plus the “never shared” guarantees.
+
+**User wants to turn off creator-directed sharing for one skill**
+
+> Run `selftune contributions revoke <skill>`.
+
+**User wants future creator-directed prompts to default one way**
+
+> Run `selftune contributions default <ask|always|never>` using the user's preference.
+
+**User wants to send staged creator-directed signals now**
+
+> Run `selftune contributions upload`.
+> Use `--dry-run` first if they want to confirm how many staged rows are pending.
+> Use `--retry-failed` if earlier relay attempts failed and need to be retried.
+> Use `--limit 25` when they want a smaller controlled batch.
+
+**User wants to clear all stored creator-directed contribution preferences**
+
+> Run `selftune contributions reset`.

package/skill/Workflows/CreatorContributions.md

@@ -0,0 +1,74 @@
+# selftune Creator-Contributions Workflow
+
+Manage the creator-side `selftune.contribute.json` file bundled with a skill.
+
+This is **not** the same as:
+- `selftune contributions` — end-user opt-in / opt-out preferences
+- `selftune contribute` — community export bundle
+
+## When to Use
+
+- The user is a skill creator and wants to enable creator-directed contribution for one skill
+- The user wants to inspect or remove a bundled `selftune.contribute.json`
+- The user wants to prepare a skill package for the future creator ← user relay pipeline
+
+## Default Commands
+
+```bash
+selftune creator-contributions
+selftune creator-contributions status --skill <name>
+selftune creator-contributions enable --skill <name> [--skill-path <path>] [--creator-id <id>]
+selftune creator-contributions enable --all [--prefix sc-] [--creator-id <id>]
+selftune creator-contributions disable --skill <name> [--skill-path <path>]
+```
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `--skill <name>` | Skill name to inspect or configure |
+| `--skill-path <path>` | Explicit path to the skill's `SKILL.md` when auto-discovery is ambiguous |
+| `--creator-id <id>` | Explicit creator ID. If omitted, selftune uses `alpha.cloud_user_id` from local config when available |
+| `--signals <csv>` | Comma-separated signal list for the generated config |
+| `--message <text>` | Custom opt-in note stored in the config |
+| `--privacy-url <url>` | Optional creator privacy URL stored in the config |
+| `--all` | Enable configs for every installed skill selftune can resolve |
+| `--prefix <prefix>` | Limit `--all` to installed skills whose names start with this prefix |
+
+## What It Does Today
+
+- Discovers installed skills that already ship `selftune.contribute.json`
+- Creates or removes that config file locally for a creator-owned skill
+- Can bulk-enable configs for multiple installed skills (useful for a skill suite like `sc-*`)
+- Uses a static JSON config only — no executable creator code
+
+## Notes
+
+- This is local packaging/setup only. It does **not** upload creator-directed signals yet.
+- The creator ID is currently sourced from `--creator-id` or the local alpha identity's `cloud_user_id`.
+- Use this workflow when the user is preparing a skill package.
+
+## Common Patterns
+
+**User wants to see which of their skills already request creator contributions**
+
+> Run `selftune creator-contributions` and summarize the discovered configs.
+> Example: `selftune creator-contributions status --skill sc-search`
+
+**User wants to enable creator contributions for one skill**
+
+> Run `selftune creator-contributions enable --skill <name>`.
+> If auto-discovery fails, rerun with `--skill-path /path/to/SKILL.md`.
+> If no creator identity is available locally, rerun with `--creator-id <id>`.
+> Example: `selftune creator-contributions enable --skill sc-search --skill-path ./skills/sc-search/SKILL.md --creator-id cr_state_change --signals trigger,grade,miss_category --message "Share privacy-safe usage signals with the skill creator." --privacy-url https://statechange.ai/privacy`
+
+**User wants to enable creator contributions for a whole installed skill suite**
+
+> Run `selftune creator-contributions enable --all --prefix sc-`.
+> This is the fastest path when preparing a whole family of skills like State Change skills.
+> Example: `selftune creator-contributions enable --all --prefix sc- --creator-id cr_state_change`
+
+**User wants to stop bundling creator contribution config**
+
+> Run `selftune creator-contributions disable --skill <name>`.
+> Example: `selftune creator-contributions disable --skill sc-search --skill-path ./skills/sc-search/SKILL.md`

package/skill/Workflows/Dashboard.md

@@ -49,6 +49,7 @@ override.
 | `POST` | `/api/actions/watch`       | Trigger `selftune watch` for a skill                       |
 | `POST` | `/api/actions/evolve`      | Trigger `selftune evolve` for a skill                      |
 | `POST` | `/api/actions/rollback`    | Trigger `selftune evolve rollback` for a skill             |
+| `POST` | `/api/actions/watchlist`   | Persist creator watchlist preferences                      |
 
 ### Live Updates (SSE)
 
@@ -98,6 +99,36 @@ All action endpoints return:
 
 On failure, `success` is `false` and `error` contains the error message.
 
+**Watchlist** request body:
+
+```json
+{
+  "skills": ["pptx", "sc-search"]
+}
+```
+
+`skills` must be an array of skill names. The action replaces the full persisted
+watchlist for the local dashboard.
+
+Watchlist success response:
+
+```json
+{
+  "success": true,
+  "watched_skills": ["pptx", "sc-search"],
+  "error": null
+}
+```
+
+Watchlist failure response:
+
+```json
+{
+  "success": false,
+  "error": "Missing required field: skills[]"
+}
+```
+
 ### Browser and Shutdown
 
 The live server auto-opens the dashboard URL in the default browser on

package/skill/Workflows/Evals.md

@@ -25,7 +25,7 @@ selftune eval generate --skill <name> [options]
 | Flag                               | Description                                           | Default                           |
 | ---------------------------------- | ----------------------------------------------------- | --------------------------------- |
 | `--skill <name>`                   | Skill to generate evals for                           | Required (unless `--list-skills`) |
-| `--list-skills`                    | List all logged skills with query counts              | Off                               |
+| `--list-skills`                    | List skills with trusted-vs-raw readiness counts      | Off                               |
 | `--stats`                          | Show aggregate telemetry stats for the skill          | Off                               |
 | `--max <n>`                        | Maximum eval entries per side                         | 50                                |
 | `--seed <n>`                       | Seed for deterministic shuffling                      | 42                                |
@@ -36,6 +36,7 @@ selftune eval generate --skill <name> [options]
 | `--query-log <path>`               | Path to all_queries_log.jsonl                         | Default log path                  |
 | `--telemetry-log <path>`           | Path to session_telemetry_log.jsonl                   | Default log path                  |
 | `--synthetic`                      | Generate evals from SKILL.md via LLM (no logs needed) | Off                               |
+| `--auto-synthetic`                 | Fall back to SKILL.md-based cold-start evals when no trusted triggers exist | Off                  |
 | `--skill-path <path>`              | Path to SKILL.md (required with `--synthetic`)        | —                                 |
 | `--model <model>`                  | LLM model to use for synthetic generation             | Agent default                     |
 
@@ -65,8 +66,22 @@ and optional `invocation_type` (omitted when `--no-taxonomy` is set).
 ```json
 {
   "skills": [
-    { "name": "pptx", "query_count": 42, "session_count": 15 },
-    { "name": "selftune", "query_count": 28, "session_count": 10 }
+    {
+      "name": "pptx",
+      "trusted_trigger_count": 42,
+      "raw_trigger_count": 42,
+      "trusted_session_count": 15,
+      "raw_session_count": 15,
+      "readiness": "log-ready"
+    },
+    {
+      "name": "sc-search",
+      "trusted_trigger_count": 0,
+      "raw_trigger_count": 1,
+      "trusted_session_count": 0,
+      "raw_session_count": 1,
+      "readiness": "cold-start"
+    }
   ]
 }
 ```
@@ -115,7 +130,11 @@ Discover which skills have telemetry data and how many queries each has.
 selftune eval generate --list-skills
 ```
 
-Run this first to identify which skills have enough data for eval generation.
+Run this first to identify which skills have enough trusted data for eval generation.
+Installed skills with no trusted trigger history now appear as `cold-start`, which means the
+skill is installed locally and ready for `--auto-synthetic` / `--synthetic` eval generation.
+If raw trigger history exists but trusted positives do not, the list now shows both counts so the
+creator can see that telemetry exists without being misled into thinking the skill is fully ready.
 
 ### Generate Synthetic Evals (Cold Start)
 
@@ -126,20 +145,36 @@ queries directly from the SKILL.md content via an LLM.
 selftune eval generate --skill pptx --synthetic --skill-path /path/to/skills/pptx/SKILL.md
 ```
 
+If the skill is installed locally but has no trusted trigger history yet, use the faster creator
+onboarding path:
+
+```bash
+selftune eval generate --skill pptx --auto-synthetic --skill-path /path/to/skills/pptx/SKILL.md
+```
+
+`--auto-synthetic` keeps the normal log-based path when real trigger data exists, but falls back
+to synthetic cold-start generation when it does not.
+
 The command:
 
 1. Reads the SKILL.md file content
 2. Loads real user queries from the database (if available) as few-shot style examples so synthetic queries match real phrasing patterns
-3. Sends skill content and real examples to an LLM with a prompt requesting realistic test queries
-4. Parses the response into eval entries with invocation type annotations
-5. Classifies each positive query using the deterministic `classifyInvocation()` heuristic
-6. Writes the eval set to the output file
+3. Detects nearby installed sibling skills to generate harder negative controls
+4. Over-generates a candidate pool with a balanced prompt family mix (explicit / implicit / contextual positives plus sibling-confusion / adjacent / unrelated negatives)
+5. Runs a second critique/prune pass to remove weak paraphrases, overlaps, and blurry boundary cases
+6. Parses the response into eval entries with invocation type annotations
+7. Classifies each positive query using the deterministic `classifyInvocation()` heuristic
+8. Writes the eval set to the output file
 
 **Note:** When real query data exists in the database, synthetic generation
 automatically includes high-confidence positive triggers and general queries as
 phrasing references. This produces more natural-sounding eval queries. If no
 database is available, generation proceeds without real examples (fail-open).
 
+The synthetic cold-start path is intentionally small and targeted. It is meant to bootstrap a
+creator skill into its first supervised evolution cycle, not serve as the long-term source of
+truth once real telemetry exists.
+
 Use `--model` to override the default LLM model:
 
 ```bash
@@ -165,6 +200,20 @@ The command:
 5. Annotates each entry with invocation type
 6. Writes the eval set to the output file
 
+After generation, the current validation path is:
+
+```bash
+selftune evolve --skill <name> --skill-path /path/to/SKILL.md --eval-set <generated-file> --dry-run
+```
+
+That dry run validates a proposal against the generated eval set without deploying.
+
+If the selected skill has no trusted positives yet but selftune can resolve a local `SKILL.md`,
+the command now prints the exact `--auto-synthetic` rerun hint instead of leaving the creator to
+guess the cold-start path.
+
+After reviewing a dry-run proposal, deploy by rerunning without `--dry-run`.
+
 ### Show Stats
 
 View aggregate telemetry for a skill: average turns, tool call breakdown,

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

@@ -192,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
@@ -271,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/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

@@ -1,9 +1,11 @@
 # selftune Repair Skill Usage Workflow
 
 Rebuild trustworthy skill-usage records by replaying Claude Code transcripts
-and Codex rollouts. Produces a repaired overlay (`skill_usage_repaired.jsonl`)
-that corrects missing or inaccurate skill paths, scopes, and query associations
-from the raw hook-captured data.
+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
 
@@ -37,7 +39,7 @@ selftune repair-skill-usage
 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. **Write repaired overlay** — Writes deduplicated records to the repaired log and updates the session marker.
+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
 
@@ -59,6 +61,11 @@ JSON summary printed to stdout:
 
 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**
@@ -72,6 +79,7 @@ With `--dry-run`, the same summary is printed but no files are written.
 **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**
 

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