selftune 0.2.16 → 0.2.19

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,25 @@ 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?"
+
 ## Steps
 
 ### 1. Run Analysis
@@ -86,6 +130,18 @@ 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
+- `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 +166,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` plus the `refactor_proposal`.

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

@@ -31,14 +31,16 @@ selftune evolve --skill <name> --skill-path <path> [options]
 | `--confidence <n>`           | Minimum confidence threshold (0-1)                                      | 0.6                            |
 | `--max-iterations <n>`       | Maximum retry iterations                                                | 3                              |
 | `--validation-model <model>` | Model for trigger-check validation LLM calls                            | `haiku`                        |
-| `--pareto`                   | Generate multiple candidates per iteration                              | Off                            |
-| `--candidates <n>`           | Number of candidates per iteration (with `--pareto`)                    | 3                              |
+| `--pareto`                   | Generate multiple candidates per iteration                              | On                             |
+| `--candidates <n>`           | Number of candidates per iteration when Pareto mode is enabled          | `3`                            |
 | `--token-efficiency`         | Optimize for token efficiency in proposals                              | Off                            |
 | `--with-baseline`            | Include a no-skill baseline comparison                                  | Off                            |
 | `--cheap-loop`               | Use cheap models for loop, expensive for final gate                     | On                             |
 | `--full-model`               | Use full-cost model throughout (disables cheap-loop)                    | Off                            |
 | `--verbose`                  | Print detailed progress during evolution                                | Off                            |
 | `--gate-model <model>`       | Model for final gate validation                                         | `sonnet` (when `--cheap-loop`) |
+| `--gate-effort <level>`      | Thinking effort for the final gate (`low|medium|high|max`)              | None                           |
+| `--adaptive-gate`            | Escalate risky gate checks to `opus` + `high` effort                    | Off                            |
 | `--proposal-model <model>`   | Model for proposal generation LLM calls                                 | None                           |
 | `--sync-first`               | Refresh source-truth telemetry before generating evals/failure patterns | Off                            |
 | `--sync-force`               | Force a full source rescan during `--sync-first`                        | Off                            |
@@ -115,7 +117,7 @@ Ask one `AskUserQuestion` at a time in this order:
    - `Single model — use one model throughout`
 4. `Advanced Options`
    Options:
-   - `Defaults (0.6 confidence, 3 iterations, single candidate) (recommended)`
+   - `Defaults (0.6 confidence, 3 iterations, 3 Pareto candidates) (recommended)`
    - `Stricter (0.7 confidence, 5 iterations)`
    - `Pareto mode (multiple candidates per iteration)`
 
@@ -146,7 +148,7 @@ Configuration Summary:
   Model:       haiku (cheap-loop: sonnet gate)
   Confidence:  0.6
   Iterations:  3
-  Pareto:      off
+  Pareto:      on (3 candidates)
 
 Proceeding...
 ```
@@ -284,15 +286,20 @@ Proposals are scored on heuristic quality criteria (no LLM required). The compos
 
 ### Stopping Criteria
 
-The evolution loop stops when any of these conditions is met (priority order):
-
-| #   | Condition          | Meaning                                             |
-| --- | ------------------ | --------------------------------------------------- |
-| 1   | **Converged**      | Pass rate >= 0.95                                   |
-| 2   | **Max iterations** | Reached `--max-iterations` limit                    |
-| 3   | **Low confidence** | Proposal confidence below `--confidence` threshold  |
-| 4   | **Plateau**        | Pass rate unchanged across 3 consecutive iterations |
-| 5   | **Continue**       | None of the above -- keep iterating                 |
+The evolution loop uses a modular stopping criteria evaluator
+(`evolution/stopping-criteria.ts`) that checks conditions in priority order
+after each validation pass. The evaluator receives the current pass rate,
+historical pass rates from previous iterations, and proposal confidence to
+make a unified stop/continue decision. The stopping reason is recorded in
+audit entries for traceability.
+
+| #   | Condition          | Meaning                                                        |
+| --- | ------------------ | -------------------------------------------------------------- |
+| 1   | **Converged**      | Pass rate >= 0.95                                              |
+| 2   | **Max iterations** | Reached `--max-iterations` limit                               |
+| 3   | **Low confidence** | Proposal confidence below `--confidence` threshold             |
+| 4   | **Plateau**        | < 1% pass rate variation across 3 consecutive iterations       |
+| 5   | **Continue**       | None of the above -- keep iterating                            |
 
 ## Cheap Loop Mode
 
@@ -310,6 +317,11 @@ The gate validation is a new step between validation and deploy. It re-runs
 `validateProposal` using the gate model. If the gate fails, the proposal is
 not deployed.
 
+When `--adaptive-gate` is enabled, selftune keeps the normal gate for low-risk
+proposals and escalates only risky ones to `opus` with `high` effort. Risk
+signals include small net lift, regressions, low proposal confidence, and
+large description broadening.
+
 ```bash
 # Cheap loop with default models
 selftune evolve --skill X --skill-path Y --cheap-loop
@@ -317,6 +329,12 @@ selftune evolve --skill X --skill-path Y --cheap-loop
 # Cheap loop with opus gate
 selftune evolve --skill X --skill-path Y --cheap-loop --gate-model opus
 
+# Cheap loop with adaptive escalation for risky proposals
+selftune evolve --skill X --skill-path Y --cheap-loop --adaptive-gate
+
+# Explicit high-effort opus gate
+selftune evolve --skill X --skill-path Y --cheap-loop --gate-model opus --gate-effort high
+
 # Manual model control without cheap-loop
 selftune evolve --skill X --skill-path Y --proposal-model haiku --validation-model sonnet
 ```

package/skill/Workflows/ExportCanonical.md

@@ -0,0 +1,121 @@
+# selftune Export Canonical Workflow
+
+Export canonical telemetry records as JSONL or as a V2 push payload for cloud
+upload. Canonical records are the normalized, platform-agnostic representation
+of sessions, prompts, skill invocations, execution facts, and normalization runs.
+
+## When to Use
+
+- The user wants to export telemetry data for external analysis
+- The user says "export canonical", "canonical export", or "canonical telemetry"
+- The agent needs to produce a push payload for manual upload inspection
+- Debugging what data would be sent to the cloud API
+
+## Default Command
+
+```bash
+selftune export-canonical
+```
+
+## Options
+
+| Flag                    | Description                                                         |
+| ----------------------- | ------------------------------------------------------------------- |
+| `--out <path>`          | Write output to a file instead of stdout                            |
+| `--platform <name>`     | Filter by platform (`claude_code`, `codex`, `opencode`, `openclaw`) |
+| `--record-kind <kind>`  | Filter by record kind (`session`, `prompt`, `skill_invocation`, `execution_fact`, `normalization_run`) |
+| `--pretty`              | Pretty-print JSON output with 2-space indentation                   |
+| `--log <path>`          | Path to canonical log file (default: `~/.claude/canonical_log.jsonl`) |
+| `--projects-dir <path>` | Claude transcript directory for fallback synthesis (default: `~/.claude/projects`) |
+| `--push-payload`        | Output as a V2 push payload envelope instead of raw JSONL           |
+
+## Output Formats
+
+### Default (JSONL)
+
+One canonical record per line:
+
+```jsonl
+{"record_kind":"session","session_id":"abc123","platform":"claude_code",...}
+{"record_kind":"prompt","prompt_id":"p1","session_id":"abc123",...}
+{"record_kind":"skill_invocation","invocation_id":"inv1","skill_name":"selftune",...}
+```
+
+### Push Payload (`--push-payload`)
+
+A single JSON envelope matching the V2 cloud upload schema:
+
+```json
+{
+  "schema_version": "2.0",
+  "client_version": "0.1.0",
+  "push_id": "uuid",
+  "normalizer_version": "1.0.0",
+  "canonical": {
+    "sessions": [...],
+    "prompts": [...],
+    "skill_invocations": [...],
+    "execution_facts": [...],
+    "normalization_runs": [...],
+    "evolution_evidence": [...],
+    "orchestrate_runs": [],
+    "grading_results": [],
+    "improvement_signals": []
+  }
+}
+```
+
+### File output (`--out`)
+
+When `--out` is specified, the data is written to the file and a JSON summary
+is printed to stdout:
+
+```json
+{
+  "ok": true,
+  "out": "/path/to/output.jsonl",
+  "count": 42,
+  "format": "jsonl",
+  "pretty": false,
+  "platform": null,
+  "record_kind": null
+}
+```
+
+## Fallback Behavior
+
+If the canonical log file is empty or does not exist, the command falls back to
+synthesizing canonical records directly from Claude Code transcripts in
+`--projects-dir`. This supports existing installs that have rich transcript
+data but have not yet generated a canonical log.
+
+## Common Patterns
+
+**Export all canonical data**
+
+> Run `selftune export-canonical > export.jsonl` to dump everything.
+
+**Export only skill invocations**
+
+> Run `selftune export-canonical --record-kind skill_invocation` to filter.
+
+**Inspect push payload before upload**
+
+> Run `selftune export-canonical --push-payload --pretty` to see exactly what would be sent to the cloud API.
+
+**Export to file with summary**
+
+> Run `selftune export-canonical --out /tmp/export.jsonl --pretty` to write data and see a count summary.
+
+**Filter by platform**
+
+> Run `selftune export-canonical --platform claude_code` to export only Claude Code records.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Empty output | No canonical log and no transcripts | Run `selftune sync` or `selftune quickstart` to ingest data first |
+| "Unknown platform" error | Invalid `--platform` value | Use one of: `claude_code`, `codex`, `opencode`, `openclaw` |
+| "Unknown record kind" error | Invalid `--record-kind` value | Use one of: `session`, `prompt`, `skill_invocation`, `execution_fact`, `normalization_run` |
+| Push payload missing evolution evidence | No evolution runs recorded | Run `selftune evolve` to generate evidence, then re-export |