selftune 0.2.18 → 0.2.20

package/skill/Workflows/Composability.md

@@ -4,12 +4,27 @@ Analyze how skills interact when triggered together in the same session.
 Detects conflict candidates — skill pairs that produce more errors when
 co-occurring than when used alone.
 
+Use the same workflow when the user is asking whether a sibling skill family
+should stay split apart or be consolidated under one parent skill.
+
 ## Default Command
 
 ```bash
 selftune eval composability --skill <name> [options]
 ```
 
+## Family Overlap Command
+
+```bash
+selftune eval family-overlap --prefix <family-> [options]
+```
+
+Or analyze an explicit set of siblings:
+
+```bash
+selftune eval family-overlap --skills <skill-a,skill-b,skill-c> [options]
+```
+
 ## Options
 
 | Flag                     | Description                            | Default                                 |
@@ -18,6 +33,16 @@ selftune eval composability --skill <name> [options]
 | `--window <n>`           | Only analyze sessions from last N days | All sessions                            |
 | `--telemetry-log <path>` | Path to telemetry log                  | `~/.claude/session_telemetry_log.jsonl` |
 
+### Family Overlap Options
+
+| Flag                    | Description                                                        | Default |
+| ----------------------- | ------------------------------------------------------------------ | ------- |
+| `--prefix <family->`    | Analyze all installed/observed sibling skills with this prefix     | Required unless `--skills` |
+| `--skills <a,b,c>`      | Analyze a specific skill family                                    | Required unless `--prefix` |
+| `--parent-skill <name>` | Override the suggested consolidated parent skill name              | Derived from prefix |
+| `--min-overlap <pct>`   | Minimum positive-query overlap to flag consolidation pressure      | `0.3` |
+| `--min-shared <n>`      | Minimum shared positive queries to flag a sibling pair             | `2` |
+
 ## Output Format
 
 ```json
@@ -60,6 +85,38 @@ The analyzer is a pure function that computes conflict scores from telemetry:
 3. Pairs with `conflict_score > 0.3` are flagged as conflict candidates
 4. Results sorted by co-occurrence count (most common first)
 
+## How Family Overlap Works
+
+The family-overlap analyzer answers a different question:
+
+1. Build a trusted positive query set for each sibling skill
+2. Compare every pair of siblings using exact-query overlap
+3. Flag pairs whose overlap crosses the configured threshold
+4. If overlap is persistent across the family, emit:
+   - consolidation recommendation
+   - draft parent skill name
+   - internal workflow mapping
+   - compatibility alias / migration notes
+
+This is for packaging questions like:
+
+- "Should `sc-search`, `sc-model`, and `sc-compare` really be one parent skill?"
+- "Are my sibling skills competing for the same user intent?"
+- "Should I stop evolving these independently and redesign the family?"
+
+When trusted telemetry is sparse, the same command also emits a
+`cold_start_suspicion` block. That is a weaker, earlier signal based on the
+installed skill surfaces:
+
+1. Frontmatter / top-level description similarity
+2. Overlap in `## When to Use` language
+3. Shared command surface (for example, siblings that both wrap `mentor search`)
+4. Synthetic sibling-confusion probes derived from those overlapping surfaces
+
+Treat `cold_start_suspicion.candidate` as architecture suspicion, not proof.
+It is meant to tell you "this family may want a parent skill" before enough
+real usage exists to confirm it through trusted positive-query overlap.
+
 ## Steps
 
 ### 1. Run Analysis
@@ -86,6 +143,19 @@ When conflict candidates are identified, present them to the user with recommend
 - Consider evolving descriptions to reduce false triggers
 - Use the `pattern-analyst` agent for deeper cross-skill analysis
 
+### 4. Investigate Family Consolidation
+
+```bash
+selftune eval family-overlap --prefix sc-
+```
+
+Interpretation:
+
+- `consolidation_candidate: false` means keep improving the sibling descriptions/workflows separately
+- `consolidation_candidate: true` means the problem is likely packaging, not just wording
+- `cold_start_suspicion.candidate: true` means installed skill surfaces already look suspicious even though trusted telemetry is still sparse
+- `refactor_proposal` is a draft for human review only; do not auto-deploy a family rewrite
+
 ## Subagent Escalation
 
 For deep cross-skill analysis beyond what the composability command provides,
@@ -110,3 +180,11 @@ resolution plan with trigger ownership recommendations.
 **"Why are sessions with multiple skills failing?"**
 
 > Run composability for each skill involved, look for high conflict scores.
+
+**"Are my State Change skills too fragmented?"**
+
+> `selftune eval family-overlap --prefix sc-`
+
+**"Should I consolidate this sibling skill family?"**
+
+> Run `selftune eval family-overlap` and look for `consolidation_candidate` when you have live evidence, or `cold_start_suspicion` when you only have installed skill surfaces plus cold-start evals.

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/Evolve.md

@@ -76,6 +76,29 @@ The evolution process writes multiple audit entries:
 | `validated` | Proposal tested against eval set | `eval_snapshot` with before/after pass rates      |
 | `deployed`  | Updated SKILL.md written to disk | `eval_snapshot` with final rates                  |
 
+Routing/body validation may also carry provenance fields such as:
+
+- `validation_mode` — `llm_judge`, `host_replay`, or `structural_guard`
+- `validation_agent` — which host/agent performed the validation
+- `validation_fixture_id` — fixture identifier when replay-backed validation is used
+- `before_pass_rate` / `after_pass_rate` — only present when trigger validation actually ran; structural-guard exits do not emit synthetic pass rates
+
+Most evolve runs today still validate through `llm_judge`. Routing evolution now
+auto-builds a replay fixture from the target skill plus installed sibling
+skills in the same registry, so replay-backed validation is preferred whenever
+that local fixture can be constructed because it captures host-style routing
+behavior instead of model judgment.
+
+The current replay path is fixture-backed: it evaluates the target routing table
+against the installed target/competing skill surfaces in a controlled replay
+fixture and records per-entry evidence. That is still a stronger signal than a
+free-form judge prompt, but you should describe it as replay-backed validation,
+not as live operator telemetry.
+
+Replay parsing is intentionally conservative: unreadable skill files degrade to
+empty surfaces instead of throwing, and malformed routing rows with empty
+trigger cells are ignored rather than treated as valid triggers.
+
 ## Parsing Instructions
 
 ### Track Evolution Progress

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 |