selftune 0.2.8 → 0.2.10

package/skill/Workflows/ImportSkillsBench.md

@@ -18,12 +18,12 @@ selftune eval import --dir <path> --skill <name> --output <path> [options]
 
 ## Options
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--dir <path>` | Path to SkillsBench tasks directory | Required |
-| `--skill <name>` | Target skill to match tasks against | Required |
-| `--output <path>` | Output eval set JSON file | Required |
-| `--match-strategy <type>` | Matching strategy: `exact` or `fuzzy` | `exact` |
+| Flag                      | Description                           | Default  |
+| ------------------------- | ------------------------------------- | -------- |
+| `--dir <path>`            | Path to SkillsBench tasks directory   | Required |
+| `--skill <name>`          | Target skill to match tasks against   | Required |
+| `--output <path>`         | Output eval set JSON file             | Required |
+| `--match-strategy <type>` | Matching strategy: `exact` or `fuzzy` | `exact`  |
 
 ## Match Strategies
 
@@ -108,10 +108,13 @@ corpus. Use the merged set with `selftune evolve --eval-set merged-evals.json`.
 ## Common Patterns
 
 **"Import SkillsBench tasks for Research"**
+
 > `selftune eval import --dir /path/tasks --skill Research --output bench-evals.json`
 
 **"Use fuzzy matching for broader coverage"**
+
 > `selftune eval import --dir /path/tasks --skill pptx --output bench-evals.json --match-strategy fuzzy`
 
 **"Enrich my eval set with external benchmarks"**
+
 > Import with `eval import`, then pass the output to `evolve --eval-set`.

package/skill/Workflows/Ingest.md

@@ -8,13 +8,13 @@ Covers five sub-commands: `ingest claude`, `ingest codex`, `ingest opencode`,
 
 ## When to Use Each
 
-| Sub-command | Platform | Mode | When |
-|-------------|----------|------|------|
-| `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 |
+| Sub-command         | Platform    | Mode      | When                                                |
+| ------------------- | ----------- | --------- | --------------------------------------------------- |
+| `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         |
 
 ---
 
@@ -30,13 +30,13 @@ 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 |
+| 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
 
@@ -46,6 +46,7 @@ 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"`
@@ -88,6 +89,7 @@ JSONL format. See `references/logs.md` for the Codex rollout format.
 ### Output
 
 Writes to:
+
 - `~/.claude/all_queries_log.jsonl` -- extracted user queries
 - `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "codex_rollout"`
 
@@ -124,6 +126,7 @@ See `references/logs.md` for the OpenCode message format.
 ### Output
 
 Writes to:
+
 - `~/.claude/all_queries_log.jsonl` -- extracted user queries
 - `~/.claude/session_telemetry_log.jsonl` -- per-session metrics with `source: "opencode"` or `"opencode_json"`
 
@@ -149,23 +152,25 @@ 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 |
+| 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"`
@@ -210,6 +215,7 @@ selftune ingest wrap-codex -- --model o3 "Fix the failing tests"
 ### Output
 
 Writes to:
+
 - `~/.claude/all_queries_log.jsonl` -- the user query
 - `~/.claude/session_telemetry_log.jsonl` -- session metrics with `source: "codex"`
 
@@ -233,30 +239,39 @@ 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/`.
 
 **"Import opencode sessions"**
+
 > 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 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 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 eval generate --list-skills` to see if the ingested sessions appear.

package/skill/Workflows/Initialize.md

@@ -18,18 +18,19 @@ selftune init --no-alpha [--force]
 
 ## Options
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--agent <type>` | Agent platform: `claude_code`, `codex`, `opencode`, `openclaw` | Auto-detected |
-| `--cli-path <path>` | Override auto-detected CLI entry-point path | Auto-detected |
-| `--force` | Reinitialize even if config already exists | Off |
-| `--enable-autonomy` | Enable autonomous scheduling during init | Off |
-| `--schedule-format <fmt>` | Schedule format: `cron`, `launchd`, `systemd` | Auto-detected |
-| `--alpha` | Enroll in the selftune alpha program | Off |
-| `--no-alpha` | Unenroll from the alpha program (preserves user_id) | Off |
-| `--alpha-email <email>` | Email for alpha enrollment (required with `--alpha`) | - |
-| `--alpha-name <name>` | Display name for alpha enrollment | - |
-| `--alpha-key <key>` | API key for cloud uploads (`st_live_*` format) | - |
+| Flag                      | Description                                                               | Default       |
+| ------------------------- | ------------------------------------------------------------------------- | ------------- |
+| `--agent <type>`          | Agent platform: `claude_code`, `codex`, `opencode`, `openclaw`            | Auto-detected |
+| `--cli-path <path>`       | Override auto-detected CLI entry-point path                               | Auto-detected |
+| `--force`                 | Reinitialize even if config already exists                                | Off           |
+| `--no-sync`               | Skip historical transcript backfill during init                           | Sync on       |
+| `--no-autonomy`           | Skip autonomous scheduling setup during init                              | Autonomy on   |
+| `--enable-autonomy`       | (Deprecated alias) Enable autonomous scheduling — now on by default       | On            |
+| `--schedule-format <fmt>` | Schedule format: `cron`, `launchd`, `systemd`                             | Auto-detected |
+| `--alpha`                 | Enroll in the selftune alpha program (opens browser for device-code auth) | Off           |
+| `--no-alpha`              | Unenroll from the alpha program (preserves user_id)                       | Off           |
+| `--alpha-email <email>`   | Email for alpha enrollment (required with `--alpha`)                      | -             |
+| `--alpha-name <name>`     | Display name for alpha enrollment                                         | -             |
 
 ## Output Format
 
@@ -46,29 +47,35 @@ Creates `~/.selftune/config.json`:
   "alpha": {
     "enrolled": true,
     "user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+    "cloud_user_id": "cloud-uuid-...",
+    "cloud_org_id": "org-uuid-...",
     "email": "user@example.com",
     "display_name": "User Name",
-    "consent_timestamp": "2026-02-28T10:00:00Z"
+    "consent_timestamp": "2026-02-28T10:00:00Z",
+    "api_key": "<provisioned automatically via device-code flow>"
   }
 }
 ```
 
 ### Field Descriptions
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `agent_type` | string | Detected or specified agent platform |
-| `cli_path` | string | Absolute path to the CLI entry point |
-| `llm_mode` | string | How LLM calls are made: `agent` or `api` |
-| `agent_cli` | string | CLI binary name for the detected agent |
-| `hooks_installed` | boolean | Whether telemetry hooks are installed |
-| `initialized_at` | string | ISO 8601 timestamp |
-| `alpha` | object? | Alpha program enrollment (present only if enrolled) |
-| `alpha.enrolled` | boolean | Whether the user is currently enrolled |
-| `alpha.user_id` | string | Stable UUID, generated once, preserved across reinits |
-| `alpha.email` | string? | Email provided at enrollment |
-| `alpha.display_name` | string? | Optional display name |
-| `alpha.consent_timestamp` | string | ISO 8601 timestamp of consent |
+| Field                     | Type    | Description                                                       |
+| ------------------------- | ------- | ----------------------------------------------------------------- |
+| `agent_type`              | string  | Detected or specified agent platform                              |
+| `cli_path`                | string  | Absolute path to the CLI entry point                              |
+| `llm_mode`                | string  | How LLM calls are made: `agent` or `api`                          |
+| `agent_cli`               | string  | CLI binary name for the detected agent                            |
+| `hooks_installed`         | boolean | Whether telemetry hooks are installed                             |
+| `initialized_at`          | string  | ISO 8601 timestamp                                                |
+| `alpha`                   | object? | Alpha program enrollment (present only if enrolled)               |
+| `alpha.enrolled`          | boolean | Whether the user is currently enrolled                            |
+| `alpha.user_id`           | string  | Stable UUID, generated once, preserved across reinits             |
+| `alpha.cloud_user_id`     | string? | Cloud account UUID (set by device-code flow)                      |
+| `alpha.cloud_org_id`      | string? | Cloud organization UUID (set by device-code flow)                 |
+| `alpha.email`             | string? | Email provided at enrollment                                      |
+| `alpha.display_name`      | string? | Optional display name                                             |
+| `alpha.consent_timestamp` | string  | ISO 8601 timestamp of consent                                     |
+| `alpha.api_key`           | string? | Upload credential (provisioned automatically by device-code flow) |
 
 ## Steps
 
@@ -112,22 +119,29 @@ The init output will report what was installed, e.g.:
 [INFO] Installed 4 selftune hook(s) into ~/.claude/settings.json: UserPromptSubmit, PreToolUse, PostToolUse, Stop
 ```
 
+For Claude Code, `selftune init` also syncs selftune's bundled specialized
+agents from `skill/agents/` into `~/.claude/agents/`. The bundled files remain
+the source of truth; the `~/.claude/agents/` copies exist only so native Claude
+Code subagent calls stay up to date.
+
 **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/Skill) | `hooks/skill-eval.ts` | Track skill triggers and Skill tool invocations |
-| `Stop` | `hooks/session-stop.ts` | Capture session telemetry |
+| 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/Skill) | `hooks/skill-eval.ts`         | Track skill triggers and Skill tool invocations |
+| `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       |
 
 **Codex agents:**
+
 - 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
 - See `Workflows/Ingest.md` for details
 
@@ -140,6 +154,7 @@ 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
@@ -166,12 +181,61 @@ selftune doctor
 Parse the JSON output. All checks should pass. If any fail, address the
 reported issues before proceeding.
 
+### 8. Sync Historical Transcripts
+
+Init automatically runs `selftune sync` to backfill existing session
+transcripts into the SQLite database. This replays Claude Code transcripts,
+Codex rollouts, OpenCode sessions, and OpenClaw sessions so the eval set
+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.
+
+### 9. Autonomy Scheduling
+
+Init automatically installs OS-level scheduling (launchd on macOS, cron/systemd
+on Linux) so `selftune orchestrate` runs in the background. This is equivalent
+to running `selftune cron setup` manually.
+
+Skip with `--no-autonomy` if you prefer manual orchestration only.
+
+### 10. Offer Alpha Enrollment
+
+After local setup passes, always offer alpha enrollment before ending the setup
+workflow.
+
+Use the `AskUserQuestion` tool to ask:
+
+- `Would you like to enroll in the selftune alpha program for cloud-synced analytics?`
+
+Options:
+
+- `Yes — enable alpha uploads and richer cloud analytics`
+- `No — keep local-only selftune`
+
+If the user chooses yes, continue with the Alpha Enrollment steps below. If they
+choose no, explicitly confirm that local-only setup is complete.
+
+### 11. Initial Data Upload
+
+After alpha enrollment succeeds and sync has backfilled historical data, init
+automatically triggers an upload cycle to push data to the cloud immediately.
+This ensures the cloud has data from the moment the user finishes setup — they
+don't have to wait for the next scheduled orchestrate run.
+
+The upload is fail-open — if it fails, init still completes successfully.
+
+Additionally, every `selftune sync` run now triggers an upload cycle when alpha
+is enrolled, so data flows to the cloud every 30 minutes (matching the sync
+schedule) rather than waiting for the 2-hour orchestrate cycle.
+
 ## 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 bundled with the skill:
+
 - `skill/settings_snippet.json` — hooks for Claude Code projects
 - `assets/activation-rules-default.json` — default auto-activation rule configuration
 
@@ -188,86 +252,73 @@ workflow covers.
 Enroll the user in the selftune alpha program for early access features.
 
 Before running the alpha command:
-1. Ask whether the user wants to opt into the selftune alpha data-sharing program
+
+1. Use `AskUserQuestion` to ask whether the user wants to opt into the selftune alpha data-sharing program
+   Options:
+   - `Yes — enable cloud-synced analytics and alpha uploads`
+   - `No — keep local-only selftune`
 2. If they opt in, ask for their email and optional display name
 3. If they decline, skip alpha enrollment and continue with plain `selftune init`
 
 The CLI stays non-interactive. The agent is responsible for collecting consent
 and the required `--alpha-email` value before invoking the command.
 
-## Alpha Enrollment (Agent-First Flow)
+## Alpha Enrollment (Device-Code Flow)
 
 The alpha program sends canonical telemetry to the selftune cloud for analysis.
-Setup is agent-first — the cloud app is a one-time control-plane handoff, not the main UX.
+Enrollment uses a device-code flow — one command, one browser approval, fully automatic.
 
 ### Setup Sequence
 
 1. **Check local config**: Run `selftune status` — look for the "Alpha Upload" section
-2. **If not linked**: Tell the user:
-   > To join the selftune alpha program, you need to create an account at https://app.selftune.dev and issue an upload credential. This is a one-time step — afterwards everything runs locally through the CLI.
-3. **User completes cloud enrollment**: Signs in, enrolls, copies the `st_live_*` credential
-4. **Store credential locally**:
+2. **If not linked**: First use `AskUserQuestion` for the opt-in decision. Only if the user says yes, collect their email and run:
 
    ```bash
-   selftune init --alpha --alpha-email <user-email> --alpha-key <st_live_credential>
+   selftune init --alpha --alpha-email <user-email> --force
    ```
 
-5. **Verify readiness**: The init command prints a readiness check. If all checks pass, alpha upload is active.
-   The readiness JSON now includes a `guidance` object with:
+3. **Browser opens automatically**: The CLI requests a device code, opens the verification URL in the browser with the code pre-filled, and polls for approval.
+4. **User approves in browser**: One click to authorize.
+5. **CLI receives credentials**: API key, cloud_user_id, and org_id are automatically provisioned and stored in `~/.selftune/config.json` with `0600` permissions.
+6. **Verify readiness**: The init command prints a readiness check. If all checks pass, alpha upload is active.
+   The readiness JSON includes a `guidance` object with:
    - `message`
    - `next_command`
    - `suggested_commands[]`
    - `blocking`
-6. **If readiness fails**: Run `selftune doctor` to diagnose. Common issues:
-   - `api_key not set` → re-run init with `--alpha-key`
-   - `api_key has invalid format` → credential must start with `st_live_` or `st_test_`
-   - `not enrolled` → re-run init with `--alpha --alpha-email <email> --alpha-key <key>`
+7. **If readiness fails**: Run `selftune doctor` to diagnose. Common issues:
+   - `not enrolled` → re-run `selftune init --alpha --alpha-email <email> --force`
+   - Device-code expired → re-run the init command (codes expire after ~15 minutes)
 
 ### Key Principle
 
-The cloud app is used **only** for:
-- Sign-in
-- Alpha enrollment
-- Upload credential issuance
-
-All other selftune operations happen through the local CLI and this agent.
+The cloud app is used **only** for the one-time browser approval during device-code auth. All other selftune operations happen through the local CLI and this agent.
 
 ### Enroll
 
 ```bash
 selftune init --alpha --alpha-email user@example.com --alpha-name "User Name" --force
-selftune init --alpha-key st_live_abc123...  # after enrollment, store the API key
 ```
 
 The `--alpha-email` flag is required. The command will:
+
 1. Generate a stable UUID (preserved across reinits)
-2. Write the alpha block to `~/.selftune/config.json`
-3. Print an `alpha_enrolled` JSON message to stdout
-4. Print the consent notice to stderr
-5. If an `--alpha-key` is provided, chmod `~/.selftune/config.json` to `0600`
+2. Request a device code from the cloud API
+3. Open the browser to the verification URL
+4. Poll until the user approves
+5. Receive and store the API key, cloud_user_id, and org_id automatically
+6. Write the alpha block to `~/.selftune/config.json` with `0600` permissions
+7. Print an `alpha_enrolled` JSON message to stdout
+8. Print the consent notice to stderr
 
 The consent notice explicitly states that the friendly alpha cohort shares raw
 prompt/query text in addition to skill/session/evolution metadata.
 
-### API Key Provisioning
-
-After enrollment, users need to configure an API key for cloud uploads:
-
-1. Create a cloud account at the selftune web app
-2. Generate an API key (format: `st_live_*`)
-3. Store the key locally:
-
-```bash
-selftune init --alpha --alpha-email <email> --alpha-key st_live_abc123... --force
-```
-
-Without an API key, alpha enrollment is recorded locally but no uploads are attempted. When a key is stored, selftune tightens the local config file permissions to `0600`.
-
 ### Upload Behavior
 
-Once enrolled and an API key is configured, `selftune orchestrate` automatically
-uploads new session, invocation, and evolution data to the cloud API at the end of
-each run. This upload step is fail-open -- errors never block the orchestrate loop.
+Once enrolled, `selftune orchestrate` automatically uploads new session,
+invocation, and evolution data to the cloud API at the end of each run.
+This upload step is fail-open -- errors never block the orchestrate loop.
 Use `selftune alpha upload` for manual uploads or `selftune alpha upload --dry-run`
 to preview what would be sent.
 
@@ -298,40 +349,30 @@ If `--alpha` is passed without `--alpha-email`, the CLI throws a JSON error:
 }
 ```
 
-When alpha readiness is evaluated after `selftune init --alpha`, the CLI emits:
-
-```json
-{
-  "alpha_readiness": {
-    "ready": false,
-    "missing": ["api_key not set"],
-    "guidance": {
-      "code": "alpha_credential_required",
-      "message": "Alpha enrollment exists, but the local upload credential is missing or invalid.",
-      "next_command": "selftune init --alpha --alpha-email user@example.com --alpha-key <st_live_key> --force",
-      "suggested_commands": ["selftune status", "selftune doctor"],
-      "blocking": true
-    }
-  }
-}
-```
+If the device-code flow fails (network error, timeout, user denied), the CLI throws
+with a descriptive error message. The agent should relay this to the user and suggest
+retrying with `selftune init --alpha --alpha-email <email> --force`.
 
 ## Common Patterns
 
 **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.
 
 **User wants alpha enrollment**
-> Ask whether they want to opt into alpha data sharing. If yes, collect email
-> and optional display name, then run `selftune init --alpha --alpha-email ...`.
-> If no, continue with plain `selftune init`.
+
+> Use `AskUserQuestion` for the yes or no opt-in decision. If yes, collect email
+> and optional display name in chat, then run `selftune init --alpha --alpha-email ...`.
+> The browser opens automatically for approval. No manual key management needed.
 
 **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 appears stale**
+
 > Run `selftune init --force` to reinitialize. Verify with `selftune doctor`.

package/skill/Workflows/Orchestrate.md

@@ -22,17 +22,17 @@ 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 |
-| `--auto-approve` | *(Deprecated)* Autonomous mode is now the default | — |
-| `--skill <name>` | Limit the loop to one skill | All skills |
-| `--max-skills <n>` | Cap how many candidates are processed in one run | `5` |
-| `--recent-window <hours>` | Window for post-deploy watch/rollback checks | `48` |
-| `--sync-force` | Force a full source replay before candidate selection | Off |
-| `--loop` | Run as a long-lived process that cycles continuously | Off |
-| `--loop-interval <seconds>` | Pause between cycles (minimum 60) | `3600` |
+| Flag                        | Description                                                | Default    |
+| --------------------------- | ---------------------------------------------------------- | ---------- |
+| `--dry-run`                 | Plan and validate without deploying changes                | Off        |
+| `--review-required`         | Keep validated changes in review mode instead of deploying | Off        |
+| `--auto-approve`            | _(Deprecated)_ Autonomous mode is now the default          | —          |
+| `--skill <name>`            | Limit the loop to one skill                                | All skills |
+| `--max-skills <n>`          | Cap how many candidates are processed in one run           | `5`        |
+| `--recent-window <hours>`   | Window for post-deploy watch/rollback checks               | `48`       |
+| `--sync-force`              | Force a full source replay before candidate selection      | Off        |
+| `--loop`                    | Run as a long-lived process that cycles continuously       | Off        |
+| `--loop-interval <seconds>` | Pause between cycles (minimum 60)                          | `3600`     |
 
 ## Default Behavior
 
@@ -46,22 +46,27 @@ 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.
 
@@ -94,11 +99,11 @@ This is the recommended runtime for recurring autonomous scheduling.
 
 `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 |
+| 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
@@ -123,6 +128,7 @@ 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