selftune 0.1.4 → 0.2.1

package/skill/Workflows/Ingest.md

@@ -1,27 +1,79 @@
 # selftune Ingest Workflow
 
-Import sessions from non-Claude-Code agent platforms into the shared
-selftune log format. Covers three sub-commands: `ingest-codex`,
-`ingest-opencode`, and `wrap-codex`.
+> **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: `ingest claude`, `ingest codex`, `ingest opencode`,
+`ingest openclaw`, and `ingest wrap-codex`.
 
 ## When to Use Each
 
 | Sub-command | Platform | Mode | When |
 |-------------|----------|------|------|
-| `ingest-codex` | Codex | Batch | Import existing Codex rollout logs |
-| `ingest-opencode` | OpenCode | Batch | Import existing OpenCode 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 |
+
+---
+
+## ingest claude
+
+Batch ingest existing Claude Code session transcripts into the shared JSONL schema.
+
+### Default Command
+
+```bash
+selftune ingest claude
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--since <date>` | Only ingest sessions modified after this date (e.g., `2026-01-01`) |
+| `--dry-run` | Show what would be ingested without writing to logs |
+| `--force` | Re-ingest all sessions, ignoring the marker file |
+| `--verbose` | Show per-file progress during ingestion |
+| `--projects-dir <path>` | Override default `~/.claude/projects/` directory |
+
+### Source
+
+Reads from `~/.claude/projects/<hash>/<session-id>.jsonl`. These are the
+transcript files Claude Code automatically saves for every session.
+
+### Output
+
+Writes to:
+- `~/.claude/all_queries_log.jsonl` -- extracted user queries (one per query, not just last)
+- `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "claude_code_replay"`
+- `~/.claude/skill_usage_log.jsonl` -- skill triggers with `source: "claude_code_replay"`
+
+### Steps
+
+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 eval generate --list-skills` to see if the ingested sessions appear
+
+### Notes
+
+- Idempotent: uses a marker file (`~/.claude/claude_code_ingested_sessions.json`) to track
+  which transcripts have already been ingested. Safe to run repeatedly.
+- Extracts ALL user queries per session, not just the last one.
+- Filters out system messages, short queries (<4 chars), and queries matching `SKIP_PREFIXES`.
 
 ---
 
-## ingest-codex
+## ingest codex
 
 Batch ingest Codex rollout logs into the shared JSONL schema.
 
 ### Default Command
 
 ```bash
-selftune ingest-codex
+selftune ingest codex
 ```
 
 ### Options
@@ -42,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
@@ -78,13 +130,65 @@ 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
 
 ---
 
-## wrap-codex
+## 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.
+
+### Default Command
+
+```bash
+selftune ingest openclaw
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--agents-dir <path>` | Override default `~/.openclaw/agents/` directory |
+| `--since <date>` | Only ingest sessions modified after this date (e.g., `2026-01-01`) |
+| `--dry-run` | Show what would be ingested without writing to logs |
+| `--force` | Re-ingest all sessions, ignoring the marker file |
+| `--verbose` / `-v` | Show per-session progress during ingestion |
+
+### Source
+
+Reads from `~/.openclaw/agents/<agentId>/sessions/*.jsonl`. Each JSONL file contains:
+- Line 1 (session header): `{"type":"session","version":5,"id":"<uuid>","timestamp":"<iso>","cwd":"<path>"}`
+- Line 2+ (messages): `{"role":"user|assistant|toolResult","content":[...],"timestamp":<ms>}`
+
+### Output
+
+Writes to:
+- `~/.claude/all_queries_log.jsonl` -- extracted user queries
+- `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "openclaw"`
+- `~/.claude/skill_usage_log.jsonl` -- skill triggers with `source: "openclaw"`
+
+### Steps
+
+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 eval generate --list-skills` to see if the ingested sessions appear
+
+### Notes
+
+- Idempotent: uses a marker file to track which sessions have already been ingested.
+  Safe to run repeatedly. Use `--force` to re-ingest everything.
+- Skill detection heuristic: identifies skills by checking for `SKILL.md` file reads in
+  tool calls and by matching known skill names in assistant text content.
+- Multi-agent support: scans all agent directories under the agents root, ingesting
+  sessions from every agent found.
+
+---
+
+## ingest wrap-codex
 
 Wrap `codex exec` with real-time telemetry capture. Drop-in replacement
 that tees the JSONL stream while passing through to Codex.
@@ -92,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
@@ -100,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
@@ -119,23 +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 ingest claude`. No options needed. Reads from `~/.claude/projects/`.
+
+**"Replay only recent Claude Code sessions"**
+> 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.
+
+**"Import only recent OpenClaw sessions"**
+> 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
 
@@ -69,7 +69,7 @@ cat ~/.selftune/config.json 2>/dev/null
 ```
 
 If the file exists and is valid JSON, selftune is already initialized.
-Skip to Step 5 (verify with doctor) unless the user wants to reinitialize.
+Skip to Step 8 (verify with doctor) unless the user wants to reinitialize.
 
 ### 3. Run Init
 
@@ -77,30 +77,79 @@ Skip to Step 5 (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`. Three 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 |
 |------|--------|---------|
 | `UserPromptSubmit` | `hooks/prompt-log.ts` | Log every user query |
+| `UserPromptSubmit` | `hooks/auto-activate.ts` | Suggest skills before prompt processing |
+| `PreToolUse` (Write/Edit) | `hooks/skill-change-guard.ts` | Detect uncontrolled skill edits |
+| `PreToolUse` (Write/Edit) | `hooks/evolution-guard.ts` | Block SKILL.md edits on monitored skills |
 | `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. Verify with Doctor
+### 5. Initialize Memory Directory
+
+Create the memory directory if it does not exist:
+
+```bash
+mkdir -p ~/.selftune/memory
+```
+
+The memory system stores three files at `~/.selftune/memory/`:
+- `context.md` -- active evolution state and session context
+- `decisions.md` -- evolution decisions and rollback history
+- `plan.md` -- current priorities and evolution strategy
+
+These files are created automatically by the memory writer during evolve,
+watch, and rollback workflows. The directory just needs to exist.
+
+### 6. Set Up Activation Rules
+
+`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`
+to customize thresholds and skill mappings for your project.
+
+### 7. Verify Agent Availability
+
+`selftune init` installs the specialized agent files to `~/.claude/agents/`
+automatically. Verify they are present:
+
+```bash
+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, run `selftune init --force`
+to reinstall them.
+
+### 8. Verify with Doctor
 
 ```bash
 selftune doctor
@@ -109,15 +158,34 @@ selftune doctor
 Parse the JSON output. All checks should pass. If any fail, address the
 reported issues before proceeding.
 
+## Integration Guide
+
+For project-type-specific setup (single-skill, multi-skill, monorepo, Codex,
+OpenCode, mixed agents), see [docs/integration-guide.md](../../docs/integration-guide.md).
+
+Templates for each project type are in the `templates/` directory:
+- `templates/single-skill-settings.json` — hooks for single-skill projects
+- `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

@@ -0,0 +1,91 @@
+# 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
+
+- 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. Ingest
+extracts **all** user queries, writing one `QueryLogRecord` per message.
+This produces much richer eval data from historical sessions.
+
+## Default Command
+
+```bash
+selftune ingest claude
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--since <date>` | Only include transcripts modified after this date |
+| `--dry-run` | Preview what would be ingested without writing |
+| `--force` | Re-ingest all transcripts (ignore marker file) |
+| `--verbose` | Show detailed progress per file |
+| `--projects-dir <path>` | Override default `~/.claude/projects/` path |
+
+## Source
+
+Reads Claude Code transcripts from `~/.claude/projects/<hash>/<session>.jsonl`.
+Each transcript is a JSONL file containing user and assistant messages.
+
+## Output
+
+Writes to:
+- `~/.claude/all_queries_log.jsonl` -- one record per user query (all messages, not just last)
+- `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "claude_code_replay"`
+- `~/.claude/skill_usage_log.jsonl` -- skill triggers detected in transcripts
+
+## Idempotency
+
+Uses a marker file at `~/.claude/claude_code_ingested_sessions.json` to track
+which transcripts have already been ingested. Use `--force` to re-ingest all.
+
+## Steps
+
+### 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
+
+**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.
+
+**User wants to ingest only recent sessions**
+> Run `selftune ingest claude --since <date>` with the user's specified date.
+
+**User wants to re-ingest everything from scratch**
+> Run `selftune ingest claude --force`. This ignores the marker file and
+> rescans all transcripts.
+
+**Agent needs to verify ingestion succeeded**
+> Run `selftune doctor` after ingestion. Parse the JSON output to check
+> that log file entry counts increased.