selftune 0.2.0 → 0.2.2

package/skill/Workflows/Ingest.md

@@ -1,29 +1,31 @@
 # selftune Ingest Workflow
 
+> **Note:** Claude Code is the fully supported platform. Codex, OpenCode, and OpenClaw adapters are experimental and may have gaps.
+
 Import sessions from agent platforms into the shared selftune log format.
-Covers five sub-commands: `replay`, `ingest-codex`, `ingest-opencode`,
-`ingest-openclaw`, and `wrap-codex`.
+Covers five sub-commands: `ingest claude`, `ingest codex`, `ingest opencode`,
+`ingest openclaw`, and `ingest wrap-codex`.
 
 ## When to Use Each
 
 | Sub-command | Platform | Mode | When |
 |-------------|----------|------|------|
-| `replay` | Claude Code | Batch | Backfill logs from existing Claude Code transcripts |
-| `ingest-codex` | Codex | Batch | Import existing Codex rollout logs |
-| `ingest-opencode` | OpenCode | Batch | Import existing OpenCode sessions |
-| `ingest-openclaw` | OpenClaw | Batch | Import existing OpenClaw agent sessions |
-| `wrap-codex` | Codex | Real-time | Wrap `codex exec` to capture telemetry live |
+| `ingest claude` | Claude Code | Batch | Backfill logs from existing Claude Code transcripts |
+| `ingest codex` | Codex | Batch | Import existing Codex rollout logs |
+| `ingest opencode` | OpenCode | Batch | Import existing OpenCode sessions |
+| `ingest openclaw` | OpenClaw | Batch | Import existing OpenClaw agent sessions |
+| `ingest wrap-codex` | Codex | Real-time | Wrap `codex exec` to capture telemetry live |
 
 ---
 
-## replay
+## ingest claude
 
 Batch ingest existing Claude Code session transcripts into the shared JSONL schema.
 
 ### Default Command
 
 ```bash
-selftune replay
+selftune ingest claude
 ```
 
 ### Options
@@ -50,10 +52,10 @@ Writes to:
 
 ### Steps
 
-1. Run `selftune replay --dry-run` to preview what would be ingested
-2. Run `selftune replay` to ingest all sessions
+1. Run `selftune ingest claude --dry-run` to preview what would be ingested
+2. Run `selftune ingest claude` to ingest all sessions
 3. Run `selftune doctor` to confirm logs are healthy
-4. Run `selftune evals --list-skills` to see if the ingested sessions appear
+4. Run `selftune eval generate --list-skills` to see if the ingested sessions appear
 
 ### Notes
 
@@ -64,14 +66,14 @@ Writes to:
 
 ---
 
-## ingest-codex
+## ingest codex
 
 Batch ingest Codex rollout logs into the shared JSONL schema.
 
 ### Default Command
 
 ```bash
-selftune ingest-codex
+selftune ingest codex
 ```
 
 ### Options
@@ -92,20 +94,20 @@ Writes to:
 ### Steps
 
 1. Verify `$CODEX_HOME/sessions/` directory exists and contains session files
-2. Run `selftune ingest-codex`
+2. Run `selftune ingest codex`
 3. Verify entries were written by checking log file line counts
 4. Run `selftune doctor` to confirm logs are healthy
 
 ---
 
-## ingest-opencode
+## ingest opencode
 
 Ingest OpenCode sessions from the SQLite database.
 
 ### Default Command
 
 ```bash
-selftune ingest-opencode
+selftune ingest opencode
 ```
 
 ### Options
@@ -128,13 +130,13 @@ Writes to:
 ### Steps
 
 1. Verify the OpenCode database exists at the expected path
-2. Run `selftune ingest-opencode`
+2. Run `selftune ingest opencode`
 3. Verify entries were written by checking log file line counts
 4. Run `selftune doctor` to confirm logs are healthy
 
 ---
 
-## ingest-openclaw
+## ingest openclaw
 
 Batch ingest OpenClaw agent session histories into the shared JSONL schema.
 Supports multiple agents and auto-discovers session files across all agent directories.
@@ -142,7 +144,7 @@ Supports multiple agents and auto-discovers session files across all agent direc
 ### Default Command
 
 ```bash
-selftune ingest-openclaw
+selftune ingest openclaw
 ```
 
 ### Options
@@ -170,10 +172,10 @@ Writes to:
 
 ### Steps
 
-1. Run `selftune ingest-openclaw --dry-run` to preview what would be ingested
-2. Run `selftune ingest-openclaw` to ingest all sessions
+1. Run `selftune ingest openclaw --dry-run` to preview what would be ingested
+2. Run `selftune ingest openclaw` to ingest all sessions
 3. Run `selftune doctor` to confirm logs are healthy
-4. Run `selftune evals --list-skills` to see if the ingested sessions appear
+4. Run `selftune eval generate --list-skills` to see if the ingested sessions appear
 
 ### Notes
 
@@ -186,7 +188,7 @@ Writes to:
 
 ---
 
-## wrap-codex
+## ingest wrap-codex
 
 Wrap `codex exec` with real-time telemetry capture. Drop-in replacement
 that tees the JSONL stream while passing through to Codex.
@@ -194,7 +196,7 @@ that tees the JSONL stream while passing through to Codex.
 ### Default Command
 
 ```bash
-selftune wrap-codex -- <your codex args>
+selftune ingest wrap-codex -- <your codex args>
 ```
 
 ### Usage
@@ -202,7 +204,7 @@ selftune wrap-codex -- <your codex args>
 Everything after `--` is passed directly to `codex exec`:
 
 ```bash
-selftune wrap-codex -- --model o3 "Fix the failing tests"
+selftune ingest wrap-codex -- --model o3 "Fix the failing tests"
 ```
 
 ### Output
@@ -221,35 +223,40 @@ stream for telemetry; it does not modify Codex behavior.
 3. Session telemetry is captured automatically
 4. Verify with `selftune doctor` after first use
 
+If telemetry capture fails, check that the codex binary is accessible and that
+the target working directory exists. Inspect the wrapper's stderr output for
+error details — `wrap-codex` captures telemetry through the Codex wrapper, not
+through hooks.
+
 ---
 
 ## Common Patterns
 
 **"Backfill Claude Code sessions"**
-> Run `selftune replay`. No options needed. Reads from `~/.claude/projects/`.
+> Run `selftune ingest claude`. No options needed. Reads from `~/.claude/projects/`.
 
 **"Replay only recent Claude Code sessions"**
-> Run `selftune replay --since 2026-02-01` with an appropriate date.
+> Run `selftune ingest claude --since 2026-02-01` with an appropriate date.
 
 **"Ingest codex logs"**
-> Run `selftune ingest-codex`. No options needed. Reads from `$CODEX_HOME/sessions/`.
+> Run `selftune ingest codex`. No options needed. Reads from `$CODEX_HOME/sessions/`.
 
 **"Import opencode sessions"**
-> Run `selftune ingest-opencode`. Reads from the SQLite database automatically.
+> Run `selftune ingest opencode`. Reads from the SQLite database automatically.
 
 **"Ingest OpenClaw sessions"**
-> Run `selftune ingest-openclaw`. Reads from `~/.openclaw/agents/` automatically.
+> Run `selftune ingest openclaw`. Reads from `~/.openclaw/agents/` automatically.
 
 **"Import only recent OpenClaw sessions"**
-> Run `selftune ingest-openclaw --since 2026-02-01` with an appropriate date.
+> Run `selftune ingest openclaw --since 2026-02-01` with an appropriate date.
 
 **"Run codex through selftune"**
-> Use `selftune wrap-codex -- <codex args>` instead of `codex exec <args>` directly.
+> Use `selftune ingest wrap-codex -- <codex args>` instead of `codex exec <args>` directly.
 
 **"Batch ingest vs real-time"**
-> Use `selftune ingest-codex` or `selftune ingest-opencode` for historical sessions.
-> Use `selftune wrap-codex` for ongoing sessions. Both produce the same log format.
+> Use `selftune ingest codex` or `selftune ingest opencode` for historical sessions.
+> Use `selftune ingest wrap-codex` for ongoing sessions. Both produce the same log format.
 
 **"How do I know it worked?"**
 > Run `selftune doctor` after ingestion. Check that log files exist and are parseable.
-> Run `selftune evals --list-skills` to see if the ingested sessions appear.
+> Run `selftune eval generate --list-skills` to see if the ingested sessions appear.

package/skill/Workflows/Initialize.md

@@ -4,9 +4,9 @@ Bootstrap selftune for first-time use or after changing environments.
 
 ## When to Use
 
-- First time using selftune in a new environment
-- After switching agent platforms (Claude Code, Codex, OpenCode)
-- When `~/.selftune/config.json` does not exist
+- The user asks to set up selftune, configure selftune, or initialize selftune
+- The agent detects `~/.selftune/config.json` does not exist
+- The user has switched agent platforms (Claude Code, Codex, OpenCode)
 
 ## Default Command
 
@@ -77,11 +77,20 @@ Skip to Step 8 (verify with doctor) unless the user wants to reinitialize.
 selftune init
 ```
 
-### 4. Install Hooks (Claude Code)
+### 4. Hooks (Claude Code)
 
-If `init` reports hooks are not installed, merge the entries from
-`skill/settings_snippet.json` into `~/.claude/settings.json`. Six hooks
-are required:
+Hooks are **automatically installed** by `selftune init`. The init command
+merges selftune hook entries from `skill/settings_snippet.json` into
+`~/.claude/settings.json` without overwriting existing user hooks. If the
+hooks are already present, they are skipped (no duplicates).
+
+The init output will report what was installed, e.g.:
+
+```text
+[INFO] Installed 4 selftune hook(s) into ~/.claude/settings.json: UserPromptSubmit, PreToolUse, PostToolUse, Stop
+```
+
+**Hook reference** (for troubleshooting):
 
 | Hook | Script | Purpose |
 |------|--------|---------|
@@ -92,15 +101,12 @@ are required:
 | `PostToolUse` (Read) | `hooks/skill-eval.ts` | Track skill triggers |
 | `Stop` | `hooks/session-stop.ts` | Capture session telemetry |
 
-Derive the hook script paths from the `cli_path` field in `~/.selftune/config.json`.
-The hooks directory is at `dirname(cli_path)/hooks/`.
-
 **Codex agents:**
-- Use `wrap-codex` for real-time telemetry capture (see `Workflows/Ingest.md`)
-- Or batch-ingest existing sessions with `selftune ingest-codex`
+- Use `selftune ingest wrap-codex` for real-time telemetry capture (see `Workflows/Ingest.md`)
+- Or batch-ingest existing sessions with `selftune ingest codex`
 
 **OpenCode agents:**
-- Use `selftune ingest-opencode` to import sessions from the SQLite database
+- Use `selftune ingest opencode` to import sessions from the SQLite database
 - See `Workflows/Ingest.md` for details
 
 ### 5. Initialize Memory Directory
@@ -121,11 +127,9 @@ watch, and rollback workflows. The directory just needs to exist.
 
 ### 6. Set Up Activation Rules
 
-Copy the default activation rules template:
-
-```bash
-cp templates/activation-rules-default.json ~/.selftune/activation-rules.json
-```
+`selftune init` copies the default activation rules template to
+`~/.selftune/activation-rules.json` automatically. If the file is missing,
+run `selftune init --force` to regenerate it.
 
 The activation rules file configures auto-activation behavior -- which skills
 get suggested and under what conditions. Edit `~/.selftune/activation-rules.json`
@@ -133,16 +137,17 @@ to customize thresholds and skill mappings for your project.
 
 ### 7. Verify Agent Availability
 
-Check that the specialized agent files are present:
+`selftune init` installs the specialized agent files to `~/.claude/agents/`
+automatically. Verify they are present:
 
 ```bash
-ls .claude/agents/
+ls ~/.claude/agents/
 ```
 
 Expected agents: `diagnosis-analyst.md`, `pattern-analyst.md`,
 `evolution-reviewer.md`, `integration-guide.md`. These are used by evolve
-and doctor workflows for deeper analysis. If missing, copy them from the
-selftune repository's `.claude/agents/` directory.
+and doctor workflows for deeper analysis. If missing, run `selftune init --force`
+to reinstall them.
 
 ### 8. Verify with Doctor
 
@@ -163,15 +168,24 @@ Templates for each project type are in the `templates/` directory:
 - `templates/multi-skill-settings.json` — hooks for multi-skill projects with activation rules
 - `templates/activation-rules-default.json` — default auto-activation rule configuration
 
+## Subagent Escalation
+
+For complex project structures (monorepos, multi-skill repos, mixed agent
+platforms), spawn the `integration-guide` agent as a subagent for guided
+setup. This agent handles project-type detection, per-package configuration,
+and verification steps that go beyond what the basic init workflow covers.
+
 ## Common Patterns
 
-**"Initialize selftune"**
-> Install the CLI (`npm install -g selftune`), run `selftune init`,
-> install hooks, and verify with `selftune doctor`.
+**User asks to set up or initialize selftune**
+> Run `which selftune` to check installation. If missing, install with
+> `npm install -g selftune`. Run `selftune init`, then verify with
+> `selftune doctor`. Report results to the user.
 
-**"Hooks aren't capturing data"**
-> Run `selftune doctor` to check hook installation. Verify paths in
-> `~/.claude/settings.json` point to actual files.
+**Hooks not capturing data**
+> Run `selftune doctor` to check hook installation. Parse the JSON output
+> for failed hook checks. If paths are wrong, update
+> `~/.claude/settings.json` to point to actual files.
 
-**"Config exists but seems stale"**
-> Run `selftune init --force` to reinitialize.
+**Config exists but appears stale**
+> Run `selftune init --force` to reinitialize. Verify with `selftune doctor`.

package/skill/Workflows/Orchestrate.md

@@ -0,0 +1,139 @@
+# selftune Orchestrate Workflow
+
+Run the autonomy-first selftune loop in one command.
+
+`selftune orchestrate` is the primary closed-loop entrypoint. It runs
+source-truth sync, computes current skill health, selects candidates,
+deploys validated low-risk description changes autonomously, and watches
+recent changes with auto-rollback enabled.
+
+## When to Use
+
+- You want the full autonomous loop, not isolated subcommands
+- You want to improve skills without manually chaining `sync`, `status`, `evolve`, and `watch`
+- You want a dry-run of what selftune would change next
+- You want a stricter review policy for a single run
+
+## Default Command
+
+```bash
+selftune orchestrate
+```
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Plan and validate without deploying changes | Off |
+| `--review-required` | Keep validated changes in review mode instead of deploying | Off |
+| `--skill <name>` | Limit the loop to one skill | All skills |
+| `--max-skills <n>` | Cap how many candidates are processed in one run | `3` |
+| `--recent-window <hours>` | Window for post-deploy watch/rollback checks | `24` |
+| `--sync-force` | Force a full source replay before candidate selection | Off |
+
+## Default Behavior
+
+- Sync source-truth telemetry first
+- Prioritize critical/warning/ungraded skills with real missed-query signal
+- Deploy validated low-risk description changes automatically
+- Watch recent deployments and roll back regressions automatically
+
+Use `--review-required` only when you want a stricter policy for a specific run.
+
+## Common Patterns
+
+**User asks to improve skills or run the full loop**
+> Run `selftune orchestrate`. Parse the JSON output from stdout and the
+> phased report from stderr. Report the summary to the user.
+
+**User wants to preview changes before deploying**
+> Run `selftune orchestrate --dry-run`. Report the planned actions without
+> making any changes.
+
+**User wants to focus on a single skill**
+> Run `selftune orchestrate --skill <name>`. This limits the loop to the
+> specified skill only.
+
+**User wants manual review before deployment**
+> Run `selftune orchestrate --review-required`. Validated changes stay in
+> review mode instead of auto-deploying.
+
+**Agent needs fresh source data before orchestrating**
+> Run `selftune orchestrate --sync-force`. This forces a full source replay
+> before candidate selection.
+
+## Output
+
+### Human-readable report (stderr)
+
+A phased decision report printed to stderr so you can see exactly what happened and why:
+
+1. **Phase 1: Sync** — which sources were scanned, how many records synced, repair counts
+2. **Phase 2: Status** — skill count, system health, breakdown by status category
+3. **Phase 3: Skill Decisions** — each skill with its action (EVOLVE / WATCH / SKIP) and reason
+4. **Phase 4: Evolution Results** — validation pass-rate changes (before → after), deployment status
+5. **Phase 5: Watch** — post-deploy monitoring with alert and rollback indicators
+6. **Summary** — evaluated/deployed/watched/skipped counts and elapsed time
+
+A mode banner at the top shows DRY RUN, REVIEW, or AUTONOMOUS with rerun hints when applicable.
+
+### JSON output (stdout)
+
+Machine-readable JSON with the summary fields plus a `decisions` array containing per-skill:
+
+- `skill`, `action`, `reason`
+- `deployed`, `evolveReason`, `validation` (before/after pass rates, improved flag) — when evolved
+- `alert`, `rolledBack`, `passRate`, `recommendation` — when watched
+
+This is the recommended runtime for recurring autonomous scheduling.
+
+## Two Execution Contexts
+
+`selftune orchestrate` runs in two contexts with different callers:
+
+| Context | Caller | Token cost | When |
+|---------|--------|------------|------|
+| **Interactive** | Agent (user says "improve my skills") | Uses agent subscription | On demand |
+| **Automated (cron)** | OS scheduler (cron/launchd/systemd) | No agent session; LLM cost only if evolution triggers | Every 6 hours |
+| **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.
+
+**Cron mode:** Install OS-level scheduling with `selftune cron setup`.
+Runs as separate invocations on a schedule (default: every 6 hours).
+
+**Loop mode:** Run `selftune orchestrate --loop` for a long-running process
+that cycles continuously. Use `--loop-interval <seconds>` to set the pause
+between cycles (default: 3600s / 1 hour, minimum: 60s). Stop with Ctrl+C
+or SIGTERM — the current cycle finishes before exit.
+
+### Signal-Reactive Trigger
+
+When improvement signals are detected during a session (corrections, explicit
+requests, manual invocations), the `session-stop` hook automatically spawns a
+focused `selftune orchestrate --max-skills 2` run in the background. This
+reactive path complements the scheduled cron/loop modes by responding to signals
+immediately after the session that produced them.
+
+Guard rails:
+- Only spawns if unconsumed signals exist in `improvement_signals.jsonl`
+- Respects the orchestrate lock file — skips if another run started within 30 minutes
+- Fire-and-forget: the hook exits immediately, orchestrate runs independently
+- Silent failure: any error is swallowed so the hook never blocks Claude
+
+### Internal Workflow Chain (Autonomous Mode)
+
+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. **Evolve** — run evolution on selected candidates (pre-flight is skipped, cheap-loop mode enabled, defaults used)
+4. **Watch** — monitor recently evolved skills (auto-rollback enabled by default, `--recent-window` hours lookback)
+
+All sub-workflows run with defaults and no user interaction. The safety
+model relies on regression thresholds, automatic rollback, and SKILL.md
+backups rather than human confirmation.

package/skill/Workflows/Replay.md

@@ -1,24 +1,28 @@
-# selftune Replay Workflow
+# selftune Ingest (Claude) Workflow
+
+> **Note:** This workflow documents `selftune ingest claude`. The command was
+> renamed from `selftune replay` to `selftune ingest claude`. This file is
+> kept as `Replay.md` for routing compatibility.
 
 Backfill the shared JSONL logs from existing Claude Code conversation
 transcripts. Useful for bootstrapping selftune with historical session data.
 
 ## When to Use
 
-- New selftune installation with months of Claude Code history
-- After re-initializing logs and wanting to recover data
-- To populate eval data without waiting for new sessions
+- The user has a new selftune installation with months of Claude Code history
+- The user re-initialized logs and wants to recover data
+- The agent needs to populate eval data without waiting for new sessions
 
 ## Key Difference from Hooks
 
-Real-time hooks capture only the **last** user query per session. Replay
+Real-time hooks capture only the **last** user query per session. Ingest
 extracts **all** user queries, writing one `QueryLogRecord` per message.
 This produces much richer eval data from historical sessions.
 
 ## Default Command
 
 ```bash
-selftune replay
+selftune ingest claude
 ```
 
 ## Options
@@ -50,21 +54,38 @@ which transcripts have already been ingested. Use `--force` to re-ingest all.
 
 ## Steps
 
-1. Run `selftune replay --dry-run` to preview what would be ingested
-2. Run `selftune replay` to perform the ingestion
-3. Run `selftune doctor` to verify logs are healthy
-4. Run `selftune evals --list-skills` to see if replayed sessions appear
+### 1. Preview Ingestion
+
+Run `selftune ingest claude --dry-run`. Parse the output to check how many
+transcripts would be ingested. Report the count to the user.
+
+### 2. Run Ingestion
+
+Run `selftune ingest claude`. Parse the output for ingested session counts
+and any errors.
+
+### 3. Verify Results
+
+Run `selftune doctor` to verify logs are healthy. Run
+`selftune eval generate --list-skills` to confirm ingested sessions appear.
+
+### 4. Report Results
+
+Report the number of sessions ingested and any skills discovered to the user.
 
 ## Common Patterns
 
-**"Backfill my logs"**
-> Run `selftune replay`. No options needed.
+**User wants to backfill logs from Claude Code history**
+> Run `selftune ingest claude`. No options needed for a full backfill.
+> Parse the output and report ingested session counts.
 
-**"Only replay recent sessions"**
-> Run `selftune replay --since 2026-02-01`
+**User wants to ingest only recent sessions**
+> Run `selftune ingest claude --since <date>` with the user's specified date.
 
-**"Re-ingest everything"**
-> Run `selftune replay --force`
+**User wants to re-ingest everything from scratch**
+> Run `selftune ingest claude --force`. This ignores the marker file and
+> rescans all transcripts.
 
-**"How do I know it worked?"**
-> Run `selftune doctor` after replay. Check log file line counts increased.
+**Agent needs to verify ingestion succeeded**
+> Run `selftune doctor` after ingestion. Parse the JSON output to check
+> that log file entry counts increased.

package/skill/Workflows/Rollback.md

@@ -6,7 +6,7 @@ Records the rollback in the evolution audit log for traceability.
 ## Default Command
 
 ```bash
-selftune rollback --skill <name> --skill-path <path> [options]
+selftune evolve rollback --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -95,13 +95,13 @@ If `--proposal-id` is specified, use that instead.
 ### 2. Run Rollback
 
 ```bash
-selftune rollback --skill pptx --skill-path /path/to/SKILL.md
+selftune evolve rollback --skill pptx --skill-path /path/to/SKILL.md
 ```
 
 Or to rollback a specific proposal:
 
 ```bash
-selftune rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
+selftune evolve rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
 ```
 
 ### 3. Verify Restoration

package/skill/Workflows/Schedule.md

@@ -0,0 +1,61 @@
+# selftune Schedule Workflow
+
+Generate ready-to-use scheduling examples for automating selftune with
+standard system tools. This is the **primary automation path** — it works
+on any machine without requiring a specific agent runtime.
+
+For OpenClaw-specific scheduling, see `Workflows/Cron.md`.
+
+## When to Use
+
+- Setting up selftune automation for the first time
+- Generating crontab entries for a Linux/macOS server
+- Creating a launchd plist for a macOS machine
+- Creating a systemd timer for a Linux server
+- Understanding the selftune automation loop
+
+## The Automation Loop
+
+The core selftune automation loop is one command:
+
+```bash
+selftune orchestrate
+```
+
+`selftune orchestrate` runs source-truth sync first, selects candidate skills,
+deploys validated low-risk description changes autonomously, and watches recent
+deployments with auto-rollback enabled.
+
+## Default Command
+
+```bash
+selftune schedule
+```
+
+Outputs examples for all three scheduling systems (cron, launchd, systemd).
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--format <type>` | Output only one format: `cron`, `launchd`, or `systemd` | All formats |
+| `--install` | Write and activate scheduler artifacts for the selected/default platform | Off |
+| `--dry-run` | Preview installed files and activation commands without writing | Off |
+| `--help` | Show help message | — |
+
+## Steps
+
+1. Run `selftune schedule` to see all examples
+2. Pick the scheduling system for your platform
+3. Install them directly with `--install`, or inspect/customize the raw snippets first
+
+## Alias
+
+`selftune schedule` is now an alias for `selftune cron`. Both commands are interchangeable. See `Workflows/Cron.md` for the full cron workflow reference.
+
+## Common Patterns
+
+- **User wants quick setup on a Linux server** -- Run `selftune schedule --install --format cron`.
+- **User wants setup on macOS** -- Run `selftune schedule --install --format launchd`.
+- **User wants setup on a systemd-based server** -- Run `selftune schedule --install --format systemd`.
+- **User mentions OpenClaw** -- Use `selftune cron setup --platform openclaw` for the OpenClaw scheduler adapter. The default product path is still `selftune schedule --install`. See `Workflows/Cron.md`.