selftune 0.2.8 → 0.2.9

package/cli/selftune/orchestrate.ts

@@ -16,12 +16,12 @@ import { parseArgs } from "node:util";
 
 import { readAlphaIdentity } from "./alpha-identity.js";
 import type { UploadCycleSummary } from "./alpha-upload/index.js";
-import { ORCHESTRATE_LOCK, SELFTUNE_CONFIG_PATH, SIGNAL_LOG } from "./constants.js";
+import { ORCHESTRATE_LOCK, SELFTUNE_CONFIG_PATH } from "./constants.js";
 import type { OrchestrateRunReport, OrchestrateRunSkillAction } from "./dashboard-contract.js";
 import type { EvolveResult } from "./evolution/evolve.js";
 import { readGradingResultsForSkill } from "./grading/results.js";
 import { getDb } from "./localdb/db.js";
-import { writeOrchestrateRunToDb } from "./localdb/direct-write.js";
+import { updateSignalConsumed, writeOrchestrateRunToDb } from "./localdb/direct-write.js";
 import {
   queryEvolutionAudit,
   queryImprovementSignals,
@@ -36,13 +36,13 @@ import { computeStatus } from "./status.js";
 import type { SyncResult } from "./sync.js";
 import { createDefaultSyncOptions, syncSources } from "./sync.js";
 import type {
+  AlphaIdentity,
   EvolutionAuditEntry,
   ImprovementSignalRecord,
   QueryLogRecord,
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "./types.js";
-import { readJsonl } from "./utils/jsonl.js";
 import { detectAgent } from "./utils/llm-call.js";
 import { getSelftuneVersion, readConfiguredAgentType } from "./utils/selftune-meta.js";
 import {
@@ -123,42 +123,17 @@ export function groupSignalsBySkill(signals: ImprovementSignalRecord[]): Map<str
   return map;
 }
 
-export function markSignalsConsumed(
-  signals: ImprovementSignalRecord[],
-  runId: string,
-  signalLogPath: string = SIGNAL_LOG,
-): void {
+export function markSignalsConsumed(signals: ImprovementSignalRecord[], runId: string): void {
   try {
     if (signals.length === 0) return;
-    if (!existsSync(signalLogPath)) return;
-
-    // Build lookup set for matching pending signals
-    const pendingKeys = new Set(signals.map((s) => `${s.timestamp}|${s.session_id}`));
-
-    const allRecords = readJsonl<ImprovementSignalRecord>(signalLogPath);
-    const now = new Date().toISOString();
-    const updated = allRecords.map((record) => {
-      const key = `${record.timestamp}|${record.session_id}`;
-      if (pendingKeys.has(key) && !record.consumed) {
-        return {
-          ...record,
-          consumed: true,
-          consumed_at: now,
-          consumed_by_run: runId,
-        };
+    for (const signal of signals) {
+      const ok = updateSignalConsumed(signal.session_id, signal.query, signal.signal_type, runId);
+      if (!ok) {
+        console.error(
+          `[orchestrate] failed to mark signal consumed: session_id=${signal.session_id}, signal_type=${signal.signal_type}`,
+        );
       }
-      return record;
-    });
-
-    // Re-read to capture any signals appended between our read and write
-    const freshRecords = readJsonl<ImprovementSignalRecord>(signalLogPath);
-    const existingKeys = new Set(updated.map((r) => `${r.timestamp}|${r.session_id}`));
-    const newlyAppended = freshRecords.filter(
-      (r) => !existingKeys.has(`${r.timestamp}|${r.session_id}`),
-    );
-    const merged = [...updated, ...newlyAppended];
-
-    writeFileSync(signalLogPath, `${merged.map((r) => JSON.stringify(r)).join("\n")}\n`);
+    }
   } catch {
     // Silent on errors
   }
@@ -412,6 +387,7 @@ export interface OrchestrateDeps {
   resolveSkillPath?: (skillName: string) => string | undefined;
   readGradingResults?: (skillName: string) => ReturnType<typeof readGradingResultsForSkill>;
   readSignals?: () => ImprovementSignalRecord[];
+  readAlphaIdentity?: () => AlphaIdentity | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -729,6 +705,8 @@ export async function orchestrate(
       });
     const _resolveSkillPath = deps.resolveSkillPath ?? defaultResolveSkillPath;
     const _readGradingResults = deps.readGradingResults ?? readGradingResultsForSkill;
+    const _readAlphaIdentity =
+      deps.readAlphaIdentity ?? (() => readAlphaIdentity(SELFTUNE_CONFIG_PATH));
 
     // Lazy-load evolve and watch to avoid circular imports
     const _evolve = deps.evolve ?? (await import("./evolution/evolve.js")).evolve;
@@ -1001,7 +979,7 @@ export async function orchestrate(
     // -------------------------------------------------------------------------
     // Step 9: Alpha upload (fail-open — never blocks the orchestrate loop)
     // -------------------------------------------------------------------------
-    const alphaIdentity = readAlphaIdentity(SELFTUNE_CONFIG_PATH);
+    const alphaIdentity = _readAlphaIdentity();
     if (alphaIdentity?.enrolled) {
       try {
         console.error("[orchestrate] Running alpha upload cycle...");

package/cli/selftune/repair/skill-usage.ts

@@ -511,14 +511,17 @@ Options:
       since,
     );
     const rolloutPaths = findRolloutFiles(values["codex-home"] ?? DEFAULT_CODEX_HOME, since);
+    // SQLite-first: default paths read from SQLite; JSONL only for custom --skill-log overrides
     let rawSkillRecords: SkillUsageRecord[];
     let queryRecords: QueryLogRecord[];
-    try {
+    const skillLogPath = values["skill-log"] ?? SKILL_LOG;
+    if (skillLogPath === SKILL_LOG) {
       const db = getDb();
       rawSkillRecords = querySkillUsageRecords(db) as SkillUsageRecord[];
       queryRecords = queryQueryLog(db) as QueryLogRecord[];
-    } catch {
-      rawSkillRecords = readJsonl<SkillUsageRecord>(values["skill-log"] ?? SKILL_LOG);
+    } else {
+      // test/custom-path fallback
+      rawSkillRecords = readJsonl<SkillUsageRecord>(skillLogPath);
       queryRecords = readJsonl<QueryLogRecord>(QUERY_LOG);
     }
     const { repairedRecords, repairedSessionIds } = rebuildSkillUsageFromTranscripts(

package/cli/selftune/sync.ts

@@ -367,6 +367,7 @@ function rebuildSkillUsageOverlay(
       rawSkillRecords = readJsonl<SkillUsageRecord>(options.skillLogPath);
     }
   } else {
+    // Intentional JSONL fallback: custom --skill-log path overrides SQLite reads
     rawSkillRecords = readJsonl<SkillUsageRecord>(options.skillLogPath);
   }
   const { repairedRecords, repairedSessionIds } = rebuildSkillUsageFromTranscripts(

package/cli/selftune/types.ts

@@ -125,7 +125,7 @@ export type {
   CanonicalSessionRecord,
   CanonicalSkillInvocationRecord,
   CanonicalSourceSessionKind,
-} from "@selftune/telemetry-contract";
+} from "@selftune/telemetry-contract/types";
 // ---------------------------------------------------------------------------
 // Canonical normalization types (local + cloud projection layer)
 // ---------------------------------------------------------------------------
@@ -138,7 +138,7 @@ export {
   CANONICAL_RECORD_KINDS,
   CANONICAL_SCHEMA_VERSION,
   CANONICAL_SOURCE_SESSION_KINDS,
-} from "@selftune/telemetry-contract";
+} from "@selftune/telemetry-contract/types";
 
 // ---------------------------------------------------------------------------
 // Transcript parsing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Self-improving skills CLI for AI agents",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,7 @@
     "test:fast": "bun test $(find tests -name '*.test.ts' ! -name 'evolve.test.ts' ! -name 'integration.test.ts' ! -name 'dashboard-server.test.ts' ! -path '*/blog-proof/*')",
     "test:slow": "bun test tests/evolution/evolve.test.ts tests/evolution/integration.test.ts tests/monitoring/integration.test.ts tests/dashboard/dashboard-server.test.ts",
     "build:dashboard": "cd apps/local-dashboard && bunx vite build",
+    "link:claude-workspace": "bash scripts/link-claude-workspace.sh",
     "sync-version": "bun run scripts/sync-skill-version.ts",
     "validate:subagents": "bun run scripts/validate-subagent-docs.ts",
     "prepublishOnly": "bun run sync-version && bun run build:dashboard",

package/packages/telemetry-contract/package.json

@@ -13,12 +13,12 @@
   },
   "exports": {
     ".": "./index.ts",
+    "./schemas": "./src/schemas.ts",
     "./types": "./src/types.ts",
     "./validators": "./src/validators.ts",
-    "./schemas": "./src/schemas.ts",
     "./fixtures": "./fixtures/index.ts"
   },
   "dependencies": {
-    "zod": "^3.24.0"
+    "zod": "^4.3.6"
   }
 }

package/packages/telemetry-contract/src/index.ts

@@ -1,3 +1,2 @@
-export * from "./schemas.js";
 export * from "./types.js";
 export * from "./validators.js";

package/packages/telemetry-contract/src/schemas.ts

@@ -1,12 +1,3 @@
-/**
- * Zod validation schemas for all canonical telemetry record types
- * and the PushPayloadV2 envelope.
- *
- * This is the single source of truth -- cloud consumers should import
- * from @selftune/telemetry-contract/schemas instead of maintaining
- * their own copies.
- */
-
 import { z } from "zod";
 import {
   CANONICAL_CAPTURE_MODES,
@@ -19,8 +10,6 @@ import {
   CANONICAL_SOURCE_SESSION_KINDS,
 } from "./types.js";
 
-// ---------- Shared enum schemas ----------
-
 export const canonicalPlatformSchema = z.enum(CANONICAL_PLATFORMS);
 export const captureModeSchema = z.enum(CANONICAL_CAPTURE_MODES);
 export const sourceSessionKindSchema = z.enum(CANONICAL_SOURCE_SESSION_KINDS);
@@ -29,14 +18,12 @@ export const invocationModeSchema = z.enum(CANONICAL_INVOCATION_MODES);
 export const completionStatusSchema = z.enum(CANONICAL_COMPLETION_STATUSES);
 export const recordKindSchema = z.enum(CANONICAL_RECORD_KINDS);
 
-// ---------- Shared structural schemas ----------
-
 export const rawSourceRefSchema = z.object({
   path: z.string().optional(),
   line: z.number().int().nonnegative().optional(),
   event_type: z.string().optional(),
   raw_id: z.string().optional(),
-  metadata: z.record(z.unknown()).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
 });
 
 export const canonicalRecordBaseSchema = z.object({
@@ -54,8 +41,6 @@ export const canonicalSessionRecordBaseSchema = canonicalRecordBaseSchema.extend
   session_id: z.string().min(1),
 });
 
-// ---------- Canonical record schemas ----------
-
 export const CanonicalSessionRecordSchema = canonicalSessionRecordBaseSchema.extend({
   record_kind: z.literal("session"),
   external_session_id: z.string().optional(),
@@ -115,7 +100,7 @@ export const CanonicalExecutionFactRecordSchema = canonicalSessionRecordBaseSche
   execution_fact_id: z.string().min(1),
   occurred_at: z.string().datetime(),
   prompt_id: z.string().optional(),
-  tool_calls_json: z.record(z.number().finite()),
+  tool_calls_json: z.record(z.string(), z.number().finite()),
   total_tool_calls: z.number().int().nonnegative(),
   bash_commands_redacted: z.array(z.string()).optional(),
   assistant_turns: z.number().int().nonnegative(),
@@ -151,8 +136,6 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   raw_source_ref: rawSourceRefSchema.optional(),
 });
 
-// ---------- Orchestrate run schemas ----------
-
 export const OrchestrateRunSkillActionSchema = z.object({
   skill: z.string().min(1),
   action: z.enum(["evolve", "watch", "skip"]),
@@ -179,12 +162,12 @@ export const PushOrchestrateRunRecordSchema = z.object({
   skill_actions: z.array(OrchestrateRunSkillActionSchema),
 });
 
-// ---------- Push V2 envelope ----------
-
 export const PushPayloadV2Schema = z.object({
   schema_version: z.literal("2.0"),
   client_version: z.string().min(1),
-  push_id: z.string().uuid(),
+  // Queue-generated push IDs are typically UUIDs, but the wire contract only
+  // requires a stable non-empty idempotency key.
+  push_id: z.string().min(1),
   normalizer_version: z.string().min(1),
   canonical: z.object({
     sessions: z.array(CanonicalSessionRecordSchema).min(0),
@@ -197,8 +180,6 @@ export const PushPayloadV2Schema = z.object({
   }),
 });
 
-// ---------- Inferred types from Zod schemas ----------
-
 export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
 export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
 export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: >
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.8
+  version: 0.2.9
   category: developer-tools
 ---
 
@@ -104,8 +104,8 @@ selftune cron remove [--dry-run]
 selftune telemetry [status|enable|disable]
 selftune export    [TABLE...] [--output/-o DIR] [--since DATE]
 
-# Alpha enrollment (cloud app is control-plane only, not the main UX)
-selftune init --alpha --alpha-email <email> --alpha-key <st_live_key>
+# Alpha enrollment (device-code flow — browser opens automatically)
+selftune init --alpha --alpha-email <email>
 selftune alpha upload [--dry-run]
 selftune status                                                        # shows cloud link state + upload readiness
 ```

package/skill/Workflows/Dashboard.md

@@ -11,14 +11,11 @@ selftune dashboard
 ```
 
 Starts a Bun HTTP server with a React SPA dashboard and opens it in the
-default browser. The dashboard reads SQLite directly, but the current
-live-update invalidation path still watches JSONL logs and pushes
-updates via Server-Sent Events (SSE). That means the dashboard usually
-refreshes quickly, but SQLite-only writes can still lag until the WAL
-cutover lands. TanStack Query polling (60s) acts as a fallback. Action
-buttons trigger selftune commands directly from the dashboard. Use
-`selftune export` to generate JSONL from SQLite for debugging or
-offline analysis.
+default browser. The dashboard reads SQLite directly and uses WAL-based
+invalidation to push live updates via Server-Sent Events (SSE).
+TanStack Query polling (60s) acts as a fallback. Action buttons trigger
+selftune commands directly from the dashboard. Use `selftune export` to
+generate JSONL from SQLite for debugging or offline analysis.
 
 ## Options
 
@@ -56,11 +53,9 @@ override.
 ### Live Updates (SSE)
 
 The dashboard connects to `/api/v2/events` via Server-Sent Events.
-When watched JSONL log files change on disk, the server broadcasts an
-`update` event. The SPA invalidates all cached queries, triggering
-immediate refetches. New data usually appears quickly, but the runtime
-footer and Status page will warn when the server is still in this
-legacy JSONL watcher mode.
+The server watches the SQLite WAL file for changes and broadcasts an
+`update` event when new data is written. The SPA invalidates all cached
+queries, triggering immediate refetches (~1s latency).
 
 TanStack Query polling (60s) acts as a fallback safety net in case the
 SSE connection drops. Data also refreshes on window focus.

package/skill/Workflows/Doctor.md

@@ -40,14 +40,14 @@ None. Doctor runs all checks unconditionally.
     },
     {
       "name": "dashboard_freshness_mode",
-      "status": "warn",
-      "message": "Dashboard still uses legacy JSONL watcher invalidation"
+      "status": "pass",
+      "message": "Dashboard reads SQLite and watches WAL for live updates"
     }
   ],
   "summary": {
-    "pass": 8,
+    "pass": 9,
     "fail": 1,
-    "warn": 1,
+    "warn": 0,
     "total": 10
   },
   "healthy": false
@@ -183,9 +183,9 @@ for root cause analysis.
 **Diagnostic steps:**
 1. Check `selftune status` — look at "Alpha Upload" and "Cloud link" lines
 2. If `doctor` includes a `cloud_link` or alpha queue warning, prefer `.checks[].guidance.next_command`
-3. If "not enrolled" or "not linked": run `selftune init --alpha --alpha-email <email> --alpha-key <key>`
-4. If "enrolled (missing credential)": re-run `selftune init --alpha --alpha-email <email> --alpha-key <credential> --force`
-5. If "api_key has invalid format": credential must start with `st_live_` or `st_test_`
+3. If "not enrolled" or "not linked": run `selftune init --alpha --alpha-email <email>` (opens browser for device-code auth)
+4. If "enrolled (missing credential)": re-run `selftune init --alpha --alpha-email <email> --force` (re-authenticates via browser)
+5. If "api_key has invalid format": re-run init with `--alpha --force` to re-authenticate
 
 **Resolution:** Follow the setup sequence in Initialize workflow → Alpha Enrollment section.
 

package/skill/Workflows/Initialize.md

@@ -25,11 +25,10 @@ selftune init --no-alpha [--force]
 | `--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 |
+| `--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 | - |
-| `--alpha-key <key>` | API key for cloud uploads (`st_live_*` format) | - |
 
 ## Output Format
 
@@ -46,9 +45,12 @@ 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>"
   }
 }
 ```
@@ -66,9 +68,12 @@ Creates `~/.selftune/config.json`:
 | `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
 
@@ -195,79 +200,61 @@ Before running the alpha command:
 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**: Collect the user's 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,23 +285,9 @@ 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
 
@@ -326,7 +299,7 @@ When alpha readiness is evaluated after `selftune init --alpha`, the CLI emits:
 **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`.
+> 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

package/skill/references/logs.md

@@ -4,6 +4,12 @@ selftune writes raw legacy logs plus a canonical event log. This reference
 describes each format in detail for the skill to use when parsing sessions,
 audit trails, and cloud-ingest exports.
 
+> **Note:** JSONL files are now backup/recovery only. SQLite (`~/.selftune/selftune.db`)
+> is the sole operational store for all runtime reads. JSONL writes are retained for
+> append-only durability, but all dashboard queries, hook reads, grading, monitoring,
+> and upload staging read from SQLite. JSONL reads only occur when custom log paths
+> are provided (e.g., `--telemetry-log`, `--skill-log`) for test isolation.
+
 ---
 
 ## ~/.claude/session_telemetry_log.jsonl