trekoon 0.2.0 → 0.2.4

package/src/commands/events.ts

@@ -1,8 +1,9 @@
 import { hasFlag, parseArgs, parseStrictPositiveInt, readMissingOptionValue, readOption } from "./arg-parser";
+import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { DEFAULT_EVENT_RETENTION_DAYS, pruneEvents } from "../storage/events-retention";
 
 const EVENTS_USAGE = "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]";
@@ -62,9 +63,10 @@ export async function runEvents(context: CliContext): Promise<CliResult> {
   const retentionDays: number = parsedRetentionDays ?? DEFAULT_EVENT_RETENTION_DAYS;
   const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
   const archive: boolean = hasFlag(parsed.flags, "archive");
-  const storage = openTrekoonDatabase(context.cwd);
+  let storage: TrekoonDatabase | undefined;
 
   try {
+    storage = openTrekoonDatabase(context.cwd);
     const summary = pruneEvents(storage.db, {
       retentionDays,
       dryRun,
@@ -82,7 +84,25 @@ export async function runEvents(context: CliContext): Promise<CliResult> {
       ].join("\n"),
       data: summary,
     });
+  } catch (error: unknown) {
+    const busyFailure = sqliteBusyFailure("events.prune", error);
+    if (busyFailure !== null) {
+      return busyFailure;
+    }
+
+    const message = safeErrorMessage(error, "Unknown events prune failure.");
+    return failResult({
+      command: "events.prune",
+      human: message,
+      data: {
+        reason: "events_failed",
+      },
+      error: {
+        code: "events_failed",
+        message,
+      },
+    });
   } finally {
-    storage.close();
+    storage?.close();
   }
 }

package/src/commands/help.ts

@@ -18,15 +18,16 @@ const ROOT_HELP = [
   "",
   "Commands:",
   "  help         Show root or command help",
-  "  init         Initialize .trekoon storage and local DB",
-  "  quickstart   Show AI execution loop + task detail workflow",
-  "  wipe         Remove local Trekoon state (requires --yes)",
+  "  init         Initialize repo-shared .trekoon storage and DB",
+  "  quickstart   Show shared-storage bootstrap + AI execution loop",
+  "  wipe         Remove repo-shared Trekoon state (requires --yes)",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
   "  events       Event retention and cleanup commands",
   "  migrate      Migration status and rollback commands",
+  "  session      One-call agent orientation (diagnostics + sync + next task)",
   "  sync         Cross-branch sync commands",
   "  skills       Project-local skill install/update/link",
 ].join("\n");
@@ -35,7 +36,9 @@ const INIT_HELP = [
   "Usage: trekoon init [--json|--toon]",
   "",
   "Purpose:",
-  "  Initialize local Trekoon storage (.trekoon) and database.",
+  "  Initialize repo-scoped Trekoon storage (.trekoon) and database.",
+  "  In git worktrees, every worktree shares the same repository DB.",
+  "  Keep .trekoon gitignored; committing the SQLite DB is not a recovery path.",
   "",
   "Examples:",
   "  trekoon init",
@@ -46,14 +49,16 @@ const QUICKSTART_HELP = [
   "Usage: trekoon quickstart [--json|--toon]",
   "",
   "Purpose:",
-  "  Show the canonical Trekoon AI execution loop and task-detail workflow.",
+  "  Show shared-storage bootstrap, diagnostics, and the canonical AI loop.",
   "",
   "Flow:",
-  "  1) trekoon --toon sync status",
-  "  2) trekoon --toon task ready --limit 5",
-  "  3) trekoon --toon task next",
-  "  4) trekoon --toon dep reverse <task-or-subtask-id>",
-  "  5) trekoon --toon task update <task-id> --status in_progress",
+  "  1) trekoon --toon init",
+  "  2) trekoon --toon sync status",
+  "  3) Fail fast on recoveryRequired or tracked/ignored mismatch diagnostics",
+  "  4) trekoon --toon task ready --limit 5",
+  "  5) trekoon --toon task next",
+  "  6) trekoon --toon dep reverse <task-or-subtask-id>",
+  "  7) trekoon --toon task update <task-id> --status in_progress",
   "",
   "Examples:",
   "  trekoon quickstart",
@@ -64,17 +69,35 @@ const WIPE_HELP = [
   "Usage: trekoon wipe --yes [--json|--toon]",
   "",
   "Purpose:",
-  "  Remove local Trekoon state for the current repository.",
+  "  Remove the repository's shared Trekoon storage directory.",
+  "  In git worktrees this erases the same .trekoon state for every linked worktree.",
   "",
   "Options:",
-  "  --yes  Required safety confirmation.",
+  "  --yes  Required confirmation for destructive repo-wide removal.",
+  "",
+  "Recovery guidance:",
+  "  Use wipe only for explicit destructive recovery.",
+  "  Do not use wipe to fix gitignore mistakes or to replace bootstrap diagnostics.",
   "",
   "Examples:",
   "  trekoon wipe --yes",
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|list|show|search|replace|update|delete> [options]",
+  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete> [options]",
+  "",
+  "Create behavior:",
+  "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
+  "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  Preferred one-shot flow when the full tree is known up front.",
+  "  Uses the same compact spec grammar as epic expand and returns mappings/counts.",
+  "",
+  "Expand behavior:",
+  "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  --task <temp-key>|<title>|<description>|<status>",
+  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (use ${"@"}<temp-key> for newly declared parents)`,
+  `  --dep <source-ref>|<depends-on-ref>  (refs can be ids or ${"@"}<temp-key>)`,
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -115,7 +138,14 @@ const EPIC_HELP = [
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|list|show|ready|next|search|replace|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete> [options]",
+  "",
+  "Create-many behavior:",
+  "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
+  "  --task <temp-key>|<title>|<description>|<status>",
+  "  Rejects unexpected positional arguments and empty required fields.",
+  "  Repeated --task flags are applied in the order provided.",
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -165,7 +195,15 @@ const TASK_HELP = [
 ].join("\n");
 
 const SUBTASK_HELP = [
-  "Usage: trekoon subtask <create|list|search|replace|update|delete> [options]",
+  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete> [options]",
+  "",
+  "Create-many behavior:",
+  "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
+  "  --subtask <temp-key>|<title>|<description>|<status>",
+  "  Positional <task-id> and --task may be combined only when equal.",
+  "  Rejects extra positional arguments and empty required fields.",
+  "  Repeated --subtask flags are applied in the order provided.",
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -197,11 +235,15 @@ const SUBTASK_HELP = [
 ].join("\n");
 
 const DEP_HELP = [
-  "Usage: trekoon dep <add|remove|list|reverse> [options]",
+  "Usage: trekoon dep <add|add-many|remove|list|reverse> [options]",
   "",
   "Subcommands:",
   "  add <source-id> <depends-on-id>",
   "      Create dependency edge: source depends on depends-on.",
+  "  add-many --dep <source-ref>|<depends-on-ref> [--dep <spec> ...]",
+  "      Create validated dependency edges from compact specs in order.",
+  "      Standalone add-many resolves persisted ids only; @<temp-key>",
+  "      refs are reserved for higher-level compact batch workflows.",
   "  remove <source-id> <depends-on-id>",
   "      Remove one dependency edge if it exists.",
   "  list <source-id>",
@@ -280,6 +322,28 @@ const SYNC_HELP = [
   "  trekoon sync resolve <conflict-id> --use ours",
 ].join("\n");
 
+const SESSION_HELP = [
+  "Usage: trekoon session [--json|--toon]",
+  "",
+  "Purpose:",
+  "  One-call agent orientation. Opens DB once and returns:",
+  "    - diagnostics: storageMode, recoveryRequired, recoveryStatus",
+  "    - sync: ahead/behind counts and pendingConflicts vs main",
+  "    - next: full task tree with subtasks for the top ready candidate (null if none)",
+  "    - nextDeps: blocker list with statuses for the next task (empty if none)",
+  "    - readiness: readyCount and blockedCount across all open tasks",
+  "",
+  "Output modes:",
+  "  human  Multi-section summary (default in TTY)",
+  "  toon   Compact pipe-encoded envelope",
+  "  json   Full structured JSON envelope",
+  "",
+  "Examples:",
+  "  trekoon session",
+  "  trekoon --toon session",
+  "  trekoon --json session",
+].join("\n");
+
 const SKILLS_HELP = [
   "Usage:",
   "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
@@ -299,7 +363,8 @@ const SKILLS_HELP = [
   "",
   "Update behavior:",
   "  - Refreshes canonical SKILL file in the install path above.",
-  "  - Reports default link states for opencode/claude/pi.",
+  "  - Auto-creates or refreshes editor symlinks when editor config dir exists.",
+  "  - Skips editors with no config dir or conflicting paths.",
   "",
   "Examples:",
   "  trekoon skills install",
@@ -312,6 +377,7 @@ const SKILLS_HELP = [
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
   quickstart: QUICKSTART_HELP,
+  session: SESSION_HELP,
   wipe: WIPE_HELP,
   epic: EPIC_HELP,
   task: TASK_HELP,

package/src/commands/init.ts

@@ -1,24 +1,130 @@
-import { okResult } from "../io/output";
+import { unexpectedFailureResult } from "./error-utils";
+
+import { DomainError } from "../domain/types";
+import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+
+function buildRecoverySummary(database: TrekoonDatabase): string[] {
+  const diagnostics = database.diagnostics;
+  const lines: string[] = [];
+
+  if (diagnostics.recoveryStatus === "no_legacy_state") {
+    lines.push("Recovery status: no legacy worktree-local state detected.");
+    return lines;
+  }
+
+  if (diagnostics.recoveryStatus === "safe_auto_migrate") {
+    if (diagnostics.autoMigratedLegacyState) {
+      lines.push("Recovery status: safe auto-migrate completed.");
+      lines.push(`Imported from: ${diagnostics.importedFromLegacyDatabase}`);
+      lines.push(`Backups created: ${diagnostics.backupFiles.join(", ")}`);
+    } else {
+      lines.push("Recovery status: legacy worktree-local state detected.");
+      lines.push("Shared storage already exists; no import was required.");
+    }
+
+    lines.push(`Operator action: ${diagnostics.operatorAction}`);
+    return lines;
+  }
+
+  lines.push(`Recovery status: ${diagnostics.recoveryStatus}`);
+  lines.push(`Operator action: ${diagnostics.operatorAction}`);
+  return lines;
+}
+
+function recoveryFailureResult(error: DomainError): CliResult | null {
+  if (error.code !== "ambiguous_legacy_state" && error.code !== "tracked_ignored_mismatch") {
+    return null;
+  }
+
+  const details = error.details ?? {};
+  const status = typeof details.status === "string" ? details.status : error.code;
+  const operatorAction = typeof details.operatorAction === "string" ? details.operatorAction : error.message;
+  const legacyDatabaseFiles = Array.isArray(details.legacyDatabaseFiles) ? details.legacyDatabaseFiles : [];
+  const trackedStorageFiles = Array.isArray(details.trackedStorageFiles) ? details.trackedStorageFiles : [];
+  const humanLines: string[] = [
+    "Trekoon init requires operator action.",
+    `Recovery status: ${status}`,
+    error.message,
+    `Operator action: ${operatorAction}`,
+  ];
+
+  if (legacyDatabaseFiles.length > 0) {
+    humanLines.push(`Legacy databases: ${legacyDatabaseFiles.join(", ")}`);
+  }
+
+  if (trackedStorageFiles.length > 0) {
+    humanLines.push(`Tracked storage files: ${trackedStorageFiles.join(", ")}`);
+  }
+
+  return failResult({
+    command: "init",
+    human: humanLines.join("\n"),
+    data: {
+      status,
+      legacyDatabaseFiles,
+      trackedStorageFiles,
+      operatorAction,
+    },
+    error: {
+      code: error.code,
+      message: error.message,
+    },
+  });
+}
 
 export async function runInit(context: CliContext): Promise<CliResult> {
-  const database = openTrekoonDatabase(context.cwd);
+  let database: TrekoonDatabase | undefined;
 
   try {
+    database = openTrekoonDatabase(context.cwd);
+    const diagnostics = database.diagnostics;
+    const humanLines: string[] = [
+      "Trekoon initialized.",
+      `Storage mode: ${diagnostics.storageMode}`,
+      `Worktree root: ${diagnostics.worktreeRoot}`,
+      `Shared storage root: ${diagnostics.sharedStorageRoot}`,
+      `Storage directory: ${database.paths.storageDir}`,
+      `Database file: ${database.paths.databaseFile}`,
+      ...buildRecoverySummary(database),
+    ];
+
     return okResult({
       command: "init",
-      human: [
-        "Trekoon initialized.",
-        `Storage directory: ${database.paths.storageDir}`,
-        `Database file: ${database.paths.databaseFile}`,
-      ].join("\n"),
+      human: humanLines.join("\n"),
       data: {
+        invocationCwd: diagnostics.invocationCwd,
+        storageMode: diagnostics.storageMode,
+        repoCommonDir: diagnostics.repoCommonDir,
+        worktreeRoot: diagnostics.worktreeRoot,
+        sharedStorageRoot: diagnostics.sharedStorageRoot,
         storageDir: database.paths.storageDir,
         databaseFile: database.paths.databaseFile,
+        legacyStateDetected: diagnostics.legacyStateDetected,
+        recoveryRequired: diagnostics.recoveryRequired,
+        recoveryStatus: diagnostics.recoveryStatus,
+        legacyDatabaseFiles: diagnostics.legacyDatabaseFiles,
+        backupFiles: diagnostics.backupFiles,
+        trackedStorageFiles: diagnostics.trackedStorageFiles,
+        autoMigratedLegacyState: diagnostics.autoMigratedLegacyState,
+        importedFromLegacyDatabase: diagnostics.importedFromLegacyDatabase,
+        operatorAction: diagnostics.operatorAction,
       },
     });
+  } catch (error: unknown) {
+    if (error instanceof DomainError) {
+      const recoveryFailure = recoveryFailureResult(error);
+      if (recoveryFailure !== null) {
+        return recoveryFailure;
+      }
+    }
+
+    return unexpectedFailureResult(error, {
+      command: "init",
+      human: "Unexpected init command failure",
+    });
   } finally {
-    database.close();
+    database?.close();
   }
 }

package/src/commands/migrate.ts

@@ -1,8 +1,9 @@
 import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { describeMigrations, rollbackDatabase } from "../storage/migrations";
 
 const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
@@ -54,9 +55,10 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     });
   }
 
-  const storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
+  let storage: TrekoonDatabase | undefined;
 
   try {
+    storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
     if (subcommand === "status") {
       const status = describeMigrations(storage.db);
 
@@ -104,7 +106,12 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
 
     return usage(`Unknown migrate subcommand '${subcommand}'.`);
   } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : "Unknown migration failure.";
+    const busyFailure = sqliteBusyFailure("migrate", error);
+    if (busyFailure !== null) {
+      return busyFailure;
+    }
+
+    const message = safeErrorMessage(error, "Unknown migration failure.");
 
     return failResult({
       command: "migrate",
@@ -118,6 +125,6 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
       },
     });
   } finally {
-    storage.close();
+    storage?.close();
   }
 }

package/src/commands/quickstart.ts

@@ -7,28 +7,42 @@ const QUICKSTART_TEXT = [
   "This quickstart is aligned with .agents/skills/trekoon/SKILL.md.",
   "For agents: always use --toon for every command.",
   "",
-  "1) Local DB and worktree model",
-  "- Every worktree stores tracker state at .trekoon/trekoon.db.",
-  "- This DB stays local; it is not merged by Git automatically.",
+  "1) Shared storage model",
+  "- In git repos and worktrees, Trekoon resolves one repo-scoped .trekoon directory.",
+  "- Every worktree for the same repo points at the same .trekoon/trekoon.db file.",
+  "- Keep .trekoon gitignored: the SQLite DB is live operational state, not source.",
+  "- Committing the DB is the wrong fix for setup drift because it snapshots machine-local state.",
   "",
-  "2) Agent session-start checklist (verify setup + current state)",
-  "- 1. Verify tracker exists (or initialize once): trekoon --toon init",
-  "- 2. Check sync baseline: trekoon --toon sync status",
-  "- 3. Load active context: trekoon --toon epic list",
-  "- 4. Load active tasks: trekoon --toon task list",
-  "- 5. Load deterministic candidates: trekoon --toon task ready --limit 5",
-  "- 6. If blocked, inspect downstream impact: trekoon --toon dep reverse <task-or-subtask-id>",
+  "2) Bootstrap and agent startup (primary)",
+  "- Single call: trekoon --toon session",
+  "- Replaces: init + sync status + task next + dep list + task show in one call.",
+  "- Returns diagnostics, next ready task, its dependencies, and full task payload.",
+  "- If diagnostics show recoveryRequired or a tracked/ignored mismatch, stop and repair setup.",
+  "- Do not continue after storage mismatch, ambiguous recovery, or broken bootstrap warnings.",
+  "- In worktrees, confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root.",
+  "",
+  "2a) Bootstrap (manual/legacy — use session instead)",
+  "- 1. Initialize or verify shared storage: trekoon --toon init",
+  "- 2. Read machine diagnostics: trekoon --toon sync status",
+  "- 3. Select next task: trekoon --toon task next",
+  "- 4. Check dependencies: trekoon --toon dep list <task-id>",
+  "- 5. Show full task: trekoon --toon task show <task-id> --all",
   "",
   "3) AI execution loop (deterministic, dependency-aware)",
-  "- 1. Sync branch/worktree state: trekoon --toon sync status",
-  "- 2. Select ready work: trekoon --toon task ready --limit 5",
-  "- 3. Pick top candidate when needed: trekoon --toon task next",
-  "- 4. Check downstream blockers: trekoon --toon dep reverse <task-or-subtask-id>",
-  "- 5. Claim work and update status: trekoon --toon task update <task-id> --status in_progress",
-  "- 6. Complete with context: trekoon --toon task update <task-id> --append \"Completed implementation\" --status done",
-  "- 7. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
+  "- 1. Start or resume session: trekoon --toon session",
+  "- 2. Claim work: trekoon --toon task update <task-id> --status in_progress",
+  "- 3. Complete with context: trekoon --toon task done <task-id> --append \"Completed implementation\"",
+  "  - Replaces: update status done + task next + dep list + task show in one call.",
+  "  - Returns next ready task, its dependencies, and full task payload.",
+  "- 4. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
+  "",
+  "4) Worktree diagnostics and recovery",
+  "- Read machine fields when available: storageMode, repoCommonDir, worktreeRoot, sharedStorageRoot, databaseFile.",
+  "- sharedStorageRoot differs from worktreeRoot in linked worktrees; that is expected and should be visible.",
+  "- If recoveryRequired is true, run trekoon --toon init and follow the reported recovery action before more commands.",
+  "- If tracked and ignored storage disagree, delete the bad fix in Git and re-bootstrap local storage instead.",
   "",
-  "4) Power-user command patterns (aligned with skill)",
+  "5) Power-user command patterns (aligned with skill)",
   "- Inspect full epic tree: trekoon --toon epic show <epic-id> --all",
   "- Inspect full task payload: trekoon --toon task show <task-id> --all",
   "- Check direct dependencies before starting: trekoon --toon dep list <task-id>",
@@ -37,7 +51,7 @@ const QUICKSTART_TEXT = [
   "- Paginate deterministically: trekoon --toon task list --cursor <n>",
   "- Bulk append/status update: trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
   "",
-  "5) Task details and description",
+  "6) Task details and description",
   "- Human list and show views default to table format.",
   "- Alternate list view: add --view compact.",
   "- task/epic/subtask list defaults: open work only (in_progress/in-progress, todo), max 10.",
@@ -53,14 +67,21 @@ const QUICKSTART_TEXT = [
   "- Full task payload (including description): trekoon --toon task show <task-id> --all",
   "- Optional integration format: trekoon --json task show <task-id> --all",
   "",
-  "6) Pre-merge sync flow",
+  "7) Pre-merge sync flow",
   "- Run: trekoon --toon sync status",
   "- Pull upstream tracker events: trekoon --toon sync pull --from main",
   "- Resolve conflicts if needed: trekoon --toon sync resolve <id> --use ours",
   "- Run sync status again before opening or merging a PR.",
   "",
-  "7) Machine output examples",
+  "8) Shared-storage wipe warning",
+  "- trekoon wipe --yes removes the shared repo-scoped .trekoon directory for every worktree in the repo.",
+  "- Treat wipe as destructive recovery, not routine cleanup.",
+  "- Never use wipe as a substitute for sync, bootstrap, or gitignore fixes.",
+  "",
+  "9) Machine output examples",
   "- trekoon --toon quickstart",
+  "- trekoon --toon session",
+  "- trekoon --toon task done <task-id> --append \"Completed implementation\"",
   "- trekoon --toon task show <task-id> --all",
   "- trekoon --toon epic show <epic-id> --all",
   "- trekoon --toon sync status",
@@ -77,17 +98,24 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       localModel: {
         storageDir: ".trekoon",
         databaseFile: ".trekoon/trekoon.db",
+        storageScope: "repo-shared-across-worktrees",
+        gitPolicy: "gitignored-operational-state",
         mergeBehavior: "manual-sync",
       },
       alignedSkill: ".agents/skills/trekoon/SKILL.md",
       requiresToonForAgents: true,
-      agentStartupChecklist: [
+      bootstrapChecklist: [
+        "trekoon --toon session",
+        "Replaces: init + sync status + task next + dep list + task show in one call",
+        "Fail fast on recoveryRequired or tracked/ignored mismatch diagnostics",
+        "Confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root",
+      ],
+      bootstrapLegacy: [
         "trekoon --toon init",
         "trekoon --toon sync status",
-        "trekoon --toon epic list",
-        "trekoon --toon task list",
-        "trekoon --toon task ready --limit 5",
-        "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon task next",
+        "trekoon --toon dep list <task-id>",
+        "trekoon --toon task show <task-id> --all",
       ],
       preMergeFlow: [
         "trekoon --toon sync status",
@@ -96,11 +124,22 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon sync status",
       ],
       executionLoop: [
-        "trekoon --toon sync status",
-        "trekoon --toon task ready --limit 5",
-        "trekoon --toon task next",
-        "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon session",
         "trekoon --toon task update <task-id> --status in_progress",
+        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
+      ],
+      diagnostics: [
+        "storageMode",
+        "repoCommonDir",
+        "worktreeRoot",
+        "sharedStorageRoot",
+        "databaseFile",
+        "recoveryRequired",
+      ],
+      recoveryGuidance: [
+        "Run trekoon --toon init to bootstrap or re-bootstrap shared storage",
+        "Stop when diagnostics report tracked/ignored mismatch or ambiguous recovery",
+        "Do not commit .trekoon/trekoon.db; remove the tracked DB and keep .trekoon ignored",
       ],
       powerUserCommands: [
         "trekoon --toon epic show <epic-id> --all",
@@ -113,6 +152,8 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       ],
       machineExamples: [
         "trekoon --toon quickstart",
+        "trekoon --toon session",
+        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
         "trekoon --toon task show <task-id> --all",
         "trekoon --toon epic show <epic-id> --all",
         "trekoon --toon sync status",
@@ -120,6 +161,11 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
       ],
+      wipeWarning: {
+        command: "trekoon wipe --yes",
+        scope: "repo-wide shared storage",
+        destructive: true,
+      },
     },
   });
 }