trekoon 0.3.8 → 0.4.0

package/.agents/skills/trekoon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trekoon
-description: Use for Trekoon-based planning and execution: creating epics, tasks, and subtasks; breaking work into dependency-aware graphs; checking status and progress; planning backlog or sprint work; and coordinating agent execution from Trekoon. Prefer this whenever the user wants tracked implementation planning or Trekoon entity management, even if they do not explicitly say "Trekoon."
+description: "Use for Trekoon-based planning and execution: creating epics, tasks, and subtasks; breaking work into dependency-aware graphs; checking status and progress; planning backlog or sprint work; and coordinating agent execution from Trekoon. Prefer this whenever the user wants tracked implementation planning or Trekoon entity management, even if they do not explicitly say \"Trekoon\"."
 ---
 
 # Trekoon Skill

package/README.md

@@ -211,6 +211,7 @@ overview, kanban workspace per epic, task detail modals, and search.
 | Start an agent session | `trekoon session --epic <id>` |
 | Get next-action suggestions | `trekoon suggest --epic <id>` |
 | Check epic progress | `trekoon epic progress <id>` |
+| Export epic to Markdown | `trekoon epic export <id>` |
 | Mark a task done | `trekoon task done <id>` |
 | Sync across worktrees | `trekoon sync pull --from main` |
 | Get help | `trekoon [command] -h` |

package/docs/ai-agents.md

@@ -200,6 +200,7 @@ Use the narrowest command that answers the question:
 | A few ready options | `trekoon --toon task ready --limit 5` |
 | One task with subtasks | `trekoon --toon task show <task-id> --all` |
 | One epic tree | `trekoon --toon epic show <epic-id> --all` |
+| Export epic to Markdown | `trekoon --toon epic export <epic-id>` |
 | Repeated text in one scope | `trekoon --toon epic|task|subtask search ...` |
 
 For repeated text changes, use the safe replace loop:

package/docs/commands.md

@@ -202,6 +202,24 @@ trekoon epic progress <epic-id>
 Returns status counts (`total`, `doneCount`, `inProgressCount`, `blockedCount`,
 `todoCount`), `readyCount`, and `nextCandidate`.
 
+## Epic export
+
+```bash
+trekoon epic export <epic-id> [--path <path>] [--overwrite]
+```
+
+Writes a Markdown snapshot of the epic including tasks, subtasks, dependencies,
+external node stubs, and warnings. The output is a point-in-time artifact; the
+database remains the source of truth.
+
+- Default path: `<worktree-root>/plans/<slugified-title>.md`
+- `--path` with a file extension (e.g. `docs/plan.md`) creates that exact file
+- `--path` without an extension (e.g. `docs/plans`) creates the default-named file inside that directory
+- `--overwrite` resaves when the file already exists
+
+Returns `epicId`, `path`, `overwritten`, and `summary` counts in structured
+output.
+
 ## Session scoping
 
 ```bash

package/docs/quickstart.md

@@ -134,6 +134,20 @@ Cascades atomically through all descendants. If any descendant has an unresolved
 external dependency, the whole update fails with no partial writes. Works with
 `--status done` and `--status todo` only.
 
+## Export an epic to Markdown
+
+```bash
+trekoon epic export <epic-id>
+trekoon epic export <epic-id> --path docs/plan.md        # exact file
+trekoon epic export <epic-id> --path docs/plans           # default name inside dir
+trekoon epic export <epic-id> --overwrite
+```
+
+Writes a readable Markdown snapshot under `plans/` by default. With `--path`,
+a file extension means "write this file"; no extension means "put the default-
+named file in this directory". Use `--overwrite` to resave after the plan state
+changes.
+
 ## Check progress
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trekoon",
-  "version": "0.3.8",
-  "description": "AI-first local issue tracker CLI.",
+  "version": "0.4.0",
+  "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",
     "agent",

package/src/commands/epic.ts

@@ -36,7 +36,12 @@ import {
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { buildEpicExportBundle } from "../export/build-epic-export-bundle";
+import { resolveExportPath } from "../export/path";
+import { renderMarkdown } from "../export/render-markdown";
+import { atomicWrite, ExportWriteError } from "../export/write";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+import { resolveStoragePaths } from "../storage/path";
 
 function formatEpic(epic: EpicRecord): string {
   return `${epic.id} | ${epic.title} | ${epic.status}`;
@@ -53,6 +58,7 @@ const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const EXPAND_OPTIONS = ["task", "subtask", "dep"] as const;
 const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t"] as const;
+const EXPORT_OPTIONS = ["path", "overwrite"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
@@ -1472,10 +1478,87 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           data: { id: epicId },
         });
       }
+      case "export": {
+        const epicId: string = parsed.positional[1] ?? "";
+        const exportUnknown = findUnknownOption(parsed, EXPORT_OPTIONS);
+        if (exportUnknown !== undefined) {
+          return unknownOption("epic.export", exportUnknown, EXPORT_OPTIONS);
+        }
+
+        const missingExportOption = readMissingOptionValue(parsed.missingOptionValues, "path");
+        if (missingExportOption !== undefined) {
+          return failMissingOptionValue("epic.export", missingExportOption);
+        }
+
+        if (!epicId) {
+          return failResult({
+            command: "epic.export",
+            human: "Usage: trekoon epic export <epic-id> [--path <path>] [--overwrite]",
+            data: {},
+            error: { code: "invalid_input", message: "Missing epic ID" },
+          });
+        }
+
+        const bundle = buildEpicExportBundle(domain, epicId);
+        const markdown = renderMarkdown(bundle);
+        const storagePaths = resolveStoragePaths(context.cwd);
+        const customPath = readOption(parsed.options, "path");
+        const overwrite = hasFlag(parsed.flags, "overwrite");
+
+        const exportPath = resolveExportPath({
+          customPath,
+          epicId: bundle.epic.id,
+          epicTitle: bundle.epic.title,
+          worktreeRoot: storagePaths.worktreeRoot,
+          cwd: context.cwd,
+        });
+
+        try {
+          const result = atomicWrite({ path: exportPath, content: markdown, overwrite });
+          const action = result.overwritten ? "Updated" : "Exported";
+          return okResult({
+            command: "epic.export",
+            human: `${action} epic to ${result.path}`,
+            data: {
+              epicId: bundle.epic.id,
+              path: result.path,
+              overwritten: result.overwritten,
+              summary: bundle.summary,
+            },
+          });
+        } catch (error: unknown) {
+          if (error instanceof ExportWriteError) {
+            return failResult({
+              command: "epic.export",
+              human: error.message,
+              data: { path: exportPath, epicId: bundle.epic.id },
+              error: { code: error.code, message: error.message },
+            });
+          }
+          const fsCode = typeof error === "object" && error !== null && "code" in error ? (error as { code: string }).code : null;
+          if (fsCode === "EACCES" || fsCode === "EPERM" || fsCode === "EROFS") {
+            return failResult({
+              command: "epic.export",
+              human: `Permission denied: cannot write to ${exportPath}`,
+              data: { path: exportPath, epicId: bundle.epic.id, fsError: fsCode },
+              error: { code: "permission_denied", message: `Permission denied: ${exportPath}` },
+            });
+          }
+          if (fsCode === "EISDIR") {
+            return failResult({
+              command: "epic.export",
+              human: `Path is a directory, not a file: ${exportPath}`,
+              data: { path: exportPath, epicId: bundle.epic.id, fsError: fsCode },
+              error: { code: "invalid_path", message: `Path is a directory: ${exportPath}` },
+            });
+          }
+          throw error;
+        }
+      }
       default:
         return failResult({
           command: "epic",
-          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress>",
+          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export>",
           data: {
             args: context.args,
           },

package/src/commands/help.ts

@@ -103,7 +103,7 @@ const BOARD_HELP = [
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress> [options]",
+  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export> [options]",
   "",
   "Create:",
   "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
@@ -149,6 +149,24 @@ const EPIC_HELP = [
   "Progress:",
   "  trekoon epic progress <epic-id>",
   "  Returns done/in_progress/blocked/todo counts, readyCount, and nextCandidate.",
+  "",
+  "Export:",
+  "  trekoon epic export <epic-id> [--path <path>] [--overwrite]",
+  "  Writes a Markdown snapshot of the epic including tasks, subtasks, dependencies,",
+  "  external node stubs, and warnings. The Markdown is a point-in-time artifact;",
+  "  the database remains the source of truth.",
+  "",
+  "  Default path: <worktree-root>/plans/<slugified-title>.md",
+  "  --path <path>  Custom output path (relative or absolute).",
+  "                  With extension (e.g. docs/plan.md): creates that file.",
+  "                  Without extension (e.g. docs/plans): creates the default-named file inside.",
+  "  --overwrite     Resave if the file already exists.",
+  "",
+  "  Examples:",
+  "    trekoon epic export abc-123",
+  "    trekoon epic export abc-123 --path docs/plan.md       # writes docs/plan.md",
+  "    trekoon epic export abc-123 --path docs/plans          # writes docs/plans/<title>.md",
+  "    trekoon epic export abc-123 --overwrite",
 ].join("\n");
 
 const TASK_HELP = [

package/src/commands/quickstart.ts

@@ -59,6 +59,7 @@ const QUICKSTART_TEXT = [
   "  Bulk update:           trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
   "  Ready queue:           trekoon --toon task ready [--limit <n>] [--epic <id>]",
   "  Next candidate:        trekoon --toon task next [--epic <id>]",
+  "  Export epic to MD:     trekoon --toon epic export <epic-id> [--path <path>] [--overwrite]",
   "",
   "6) List and view defaults",
   "  Default scope: open work (in_progress, todo), limit 10.",
@@ -152,6 +153,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task list --status in_progress,todo --limit 20",
         "trekoon --toon task list --cursor <n>",
         "trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+        "trekoon --toon epic export <epic-id>",
       ],
       machineExamples: [
         "trekoon --toon quickstart",
@@ -166,6 +168,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task ready --limit 5",
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon epic export <epic-id>",
       ],
       wipeWarning: {
         command: "trekoon wipe --yes",

package/src/export/build-epic-export-bundle.ts

@@ -0,0 +1,178 @@
+import type { TrackerDomain } from "../domain/tracker-domain";
+import type { DependencyRecord, SubtaskRecord, TaskRecord } from "../domain/types";
+
+import {
+  EXPORT_SCHEMA_VERSION,
+  type ExportBundle,
+  type ExportDependencyEdge,
+  type ExportExternalNode,
+  type ExportStatusCounts,
+  type ExportSummary,
+  type ExportWarning,
+} from "./types";
+
+function countStatuses(records: readonly { readonly status: string }[]): ExportStatusCounts {
+  const counts = { total: records.length, todo: 0, inProgress: 0, done: 0, blocked: 0, other: 0 };
+  for (const record of records) {
+    if (record.status === "todo") counts.todo += 1;
+    else if (record.status === "in_progress") counts.inProgress += 1;
+    else if (record.status === "done") counts.done += 1;
+    else if (record.status === "blocked") counts.blocked += 1;
+    else counts.other += 1;
+  }
+  return counts;
+}
+
+export function buildEpicExportBundle(domain: TrackerDomain, epicId: string): ExportBundle {
+  const epic = domain.getEpicOrThrow(epicId);
+  const tasks: readonly TaskRecord[] = domain.listTasks(epicId);
+  const taskIds = new Set(tasks.map((t) => t.id));
+
+  const subtasksByTaskId = domain.listSubtasksByTaskIds(tasks.map((t) => t.id));
+  const allSubtasks: SubtaskRecord[] = [];
+  for (const task of tasks) {
+    for (const subtask of subtasksByTaskId.get(task.id) ?? []) {
+      allSubtasks.push(subtask);
+    }
+  }
+  const subtaskIds = new Set(allSubtasks.map((s) => s.id));
+
+  const inScopeIds = new Set([...taskIds, ...subtaskIds]);
+
+  // Gather all dependencies touching any in-scope node
+  const sourceIds = [...inScopeIds];
+  const dependenciesBySourceId = domain.listDependenciesBySourceIds(sourceIds);
+  const allRawDeps: DependencyRecord[] = [];
+  const seenDepIds = new Set<string>();
+  for (const deps of dependenciesBySourceId.values()) {
+    for (const dep of deps) {
+      if (!seenDepIds.has(dep.id)) {
+        seenDepIds.add(dep.id);
+        allRawDeps.push(dep);
+      }
+    }
+  }
+
+  // Also find dependencies where in-scope nodes are the target (dependsOnId)
+  // by checking each in-scope node with listDependenciesTouchingNode
+  // We use a more efficient approach: query dependencies where dependsOnId is in scope
+  for (const nodeId of inScopeIds) {
+    const touching = domain.listDependenciesTouchingNode(nodeId);
+    for (const dep of touching) {
+      if (!seenDepIds.has(dep.id)) {
+        seenDepIds.add(dep.id);
+        allRawDeps.push(dep);
+      }
+    }
+  }
+
+  // Sort for stable ordering
+  allRawDeps.sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+
+  // Classify edges and build dependency indexes
+  const blockedByMap = new Map<string, string[]>();
+  const blocksMap = new Map<string, string[]>();
+  const externalNodeMap = new Map<string, ExportExternalNode>();
+  const warnings: ExportWarning[] = [];
+
+  const edges: ExportDependencyEdge[] = allRawDeps.map((dep) => {
+    const sourceInternal = inScopeIds.has(dep.sourceId);
+    const targetInternal = inScopeIds.has(dep.dependsOnId);
+    const internal = sourceInternal && targetInternal;
+
+    // Build blockedBy: source is blocked by dependsOn
+    if (sourceInternal) {
+      const existing = blockedByMap.get(dep.sourceId) ?? [];
+      existing.push(dep.dependsOnId);
+      blockedByMap.set(dep.sourceId, existing);
+    }
+
+    // Build blocks: dependsOn blocks source
+    if (targetInternal) {
+      const existing = blocksMap.get(dep.dependsOnId) ?? [];
+      existing.push(dep.sourceId);
+      blocksMap.set(dep.dependsOnId, existing);
+    }
+
+    // Resolve external nodes
+    if (!sourceInternal && !externalNodeMap.has(dep.sourceId)) {
+      externalNodeMap.set(dep.sourceId, resolveExternalNode(domain, dep.sourceId, dep.sourceKind));
+    }
+    if (!targetInternal && !externalNodeMap.has(dep.dependsOnId)) {
+      externalNodeMap.set(dep.dependsOnId, resolveExternalNode(domain, dep.dependsOnId, dep.dependsOnKind));
+    }
+
+    return {
+      id: dep.id,
+      sourceId: dep.sourceId,
+      sourceKind: dep.sourceKind,
+      dependsOnId: dep.dependsOnId,
+      dependsOnKind: dep.dependsOnKind,
+      internal,
+    };
+  });
+
+  const externalNodes = [...externalNodeMap.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  // Check for orphaned dependency references
+  for (const node of externalNodes) {
+    if (node.title === null) {
+      warnings.push({
+        code: "orphaned_external_node",
+        message: `External ${node.kind} ${node.id} referenced by a dependency but not found in the database`,
+        entityId: node.id,
+      });
+    }
+  }
+
+  const summary: ExportSummary = {
+    taskCount: tasks.length,
+    subtaskCount: allSubtasks.length,
+    dependencyCount: edges.length,
+    externalNodeCount: externalNodes.length,
+    warningCount: warnings.length,
+    taskStatuses: countStatuses(tasks),
+    subtaskStatuses: countStatuses(allSubtasks),
+  };
+
+  return {
+    schemaVersion: EXPORT_SCHEMA_VERSION,
+    exportedAt: Date.now(),
+    epic,
+    tasks,
+    subtasks: allSubtasks,
+    dependencies: edges,
+    externalNodes,
+    blockedBy: blockedByMap,
+    blocks: blocksMap,
+    warnings,
+    summary,
+  };
+}
+
+function resolveExternalNode(
+  domain: TrackerDomain,
+  id: string,
+  kind: "task" | "subtask",
+): ExportExternalNode {
+  if (kind === "task") {
+    const task = domain.getTask(id);
+    if (task) {
+      return { id, kind: "task", title: task.title, status: task.status, epicId: task.epicId };
+    }
+  } else {
+    const subtask = domain.getSubtask(id);
+    if (subtask) {
+      const task = domain.getTask(subtask.taskId);
+      return {
+        id,
+        kind: "subtask",
+        title: subtask.title,
+        status: subtask.status,
+        epicId: task?.epicId ?? null,
+      };
+    }
+  }
+
+  return { id, kind, title: null, status: null, epicId: null };
+}

package/src/export/path.ts

@@ -0,0 +1,48 @@
+import { extname, isAbsolute, resolve } from "node:path";
+
+const PLANS_DIRNAME = "plans";
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 80);
+}
+
+function defaultFilename(epicTitle: string, epicId: string): string {
+  const slug = slugify(epicTitle) || epicId;
+  return `${slug}.md`;
+}
+
+function looksLikeFilePath(path: string): boolean {
+  return extname(path) !== "";
+}
+
+export function resolveExportPath(options: {
+  readonly customPath: string | undefined;
+  readonly epicId: string;
+  readonly epicTitle: string;
+  readonly worktreeRoot: string;
+  readonly cwd: string;
+}): string {
+  const filename = defaultFilename(options.epicTitle, options.epicId);
+
+  if (!options.customPath) {
+    return resolve(options.worktreeRoot, PLANS_DIRNAME, filename);
+  }
+
+  const resolved = isAbsolute(options.customPath)
+    ? options.customPath
+    : resolve(options.cwd, options.customPath);
+
+  // If the path has a file extension, treat it as a file path.
+  // Otherwise treat it as a directory and place the default-named file inside.
+  if (looksLikeFilePath(resolved)) {
+    return resolved;
+  }
+
+  return resolve(resolved, filename);
+}

package/src/export/render-markdown.ts

@@ -0,0 +1,256 @@
+import type { ExportBundle, ExportExternalNode, ExportStatusCounts, ExportWarning } from "./types";
+import type { SubtaskRecord, TaskRecord } from "../domain/types";
+
+export function renderMarkdown(bundle: ExportBundle): string {
+  const lines: string[] = [];
+
+  renderFrontmatter(lines, bundle);
+  renderTitle(lines, bundle);
+  renderSummaryTable(lines, bundle);
+  renderDescription(lines, bundle);
+  renderTaskIndex(lines, bundle);
+  renderTaskDetails(lines, bundle);
+  renderDependencies(lines, bundle);
+  renderExternalNodes(lines, bundle);
+  renderWarnings(lines, bundle);
+  renderFooter(lines, bundle);
+
+  return lines.join("\n") + "\n";
+}
+
+// --- Markdown escaping helpers ---
+
+function escapeTableCell(text: string): string {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+function escapeHeading(text: string): string {
+  return text.replace(/\n/g, " ").replace(/#+\s*/g, "");
+}
+
+function escapeInlineText(text: string): string {
+  return text.replace(/([[\]`*_~])/g, "\\$1").replace(/\n/g, " ");
+}
+
+function escapeBlockText(text: string): string {
+  // Descriptions are rendered as block content; preserve newlines but
+  // ensure lines that start with Markdown structural characters are safe.
+  return text
+    .split("\n")
+    .map((line) => {
+      if (/^#{1,6}\s/.test(line)) return `\\${line}`;
+      if (/^(\s*[-*+]|\s*\d+\.)\s/.test(line)) return line;
+      if (/^\s*\|/.test(line)) return `\\${line}`;
+      return line;
+    })
+    .join("\n");
+}
+
+function formatDescriptionIndented(text: string, indent: string): string {
+  return text
+    .split("\n")
+    .map((line) => `${indent}${line}`)
+    .join("\n");
+}
+
+// --- Render sections ---
+
+function renderFrontmatter(lines: string[], bundle: ExportBundle): void {
+  lines.push("---");
+  lines.push(`epic_id: ${bundle.epic.id}`);
+  lines.push(`schema_version: ${bundle.schemaVersion}`);
+  lines.push(`exported_at: ${new Date(bundle.exportedAt).toISOString()}`);
+  lines.push(`status: ${bundle.epic.status}`);
+  lines.push("---");
+  lines.push("");
+}
+
+function renderTitle(lines: string[], bundle: ExportBundle): void {
+  lines.push(`# ${escapeHeading(bundle.epic.title)}`);
+  lines.push("");
+}
+
+function renderSummaryTable(lines: string[], bundle: ExportBundle): void {
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| Metric | Count |");
+  lines.push("|--------|-------|");
+  lines.push(`| Tasks | ${bundle.summary.taskCount} |`);
+  lines.push(`| Subtasks | ${bundle.summary.subtaskCount} |`);
+  lines.push(`| Dependencies | ${bundle.summary.dependencyCount} |`);
+  lines.push(`| External nodes | ${bundle.summary.externalNodeCount} |`);
+  lines.push(`| Warnings | ${bundle.summary.warningCount} |`);
+  lines.push("");
+
+  if (bundle.summary.taskCount > 0) {
+    lines.push("### Task status breakdown");
+    lines.push("");
+    renderStatusTable(lines, bundle.summary.taskStatuses);
+    lines.push("");
+  }
+
+  if (bundle.summary.subtaskCount > 0) {
+    lines.push("### Subtask status breakdown");
+    lines.push("");
+    renderStatusTable(lines, bundle.summary.subtaskStatuses);
+    lines.push("");
+  }
+}
+
+function renderStatusTable(lines: string[], counts: ExportStatusCounts): void {
+  lines.push("| Status | Count |");
+  lines.push("|--------|-------|");
+  if (counts.todo > 0) lines.push(`| todo | ${counts.todo} |`);
+  if (counts.inProgress > 0) lines.push(`| in_progress | ${counts.inProgress} |`);
+  if (counts.done > 0) lines.push(`| done | ${counts.done} |`);
+  if (counts.blocked > 0) lines.push(`| blocked | ${counts.blocked} |`);
+  if (counts.other > 0) lines.push(`| other | ${counts.other} |`);
+}
+
+function renderDescription(lines: string[], bundle: ExportBundle): void {
+  if (!bundle.epic.description) return;
+
+  lines.push("## Description");
+  lines.push("");
+  lines.push(escapeBlockText(bundle.epic.description));
+  lines.push("");
+}
+
+function renderTaskIndex(lines: string[], bundle: ExportBundle): void {
+  if (bundle.tasks.length === 0) return;
+
+  lines.push("## Task index");
+  lines.push("");
+  lines.push("| # | Title | Status | Subtasks |");
+  lines.push("|---|-------|--------|----------|");
+
+  for (let i = 0; i < bundle.tasks.length; i++) {
+    const task = bundle.tasks[i];
+    const subtaskCount = bundle.subtasks.filter((s) => s.taskId === task.id).length;
+    const anchor = taskAnchor(task);
+    lines.push(`| ${i + 1} | [${escapeTableCell(escapeInlineText(task.title))}](#${anchor}) | ${task.status} | ${subtaskCount} |`);
+  }
+  lines.push("");
+}
+
+function renderTaskDetails(lines: string[], bundle: ExportBundle): void {
+  if (bundle.tasks.length === 0) return;
+
+  lines.push("## Tasks");
+  lines.push("");
+
+  for (const task of bundle.tasks) {
+    renderSingleTask(lines, task, bundle);
+  }
+}
+
+function renderSingleTask(lines: string[], task: TaskRecord, bundle: ExportBundle): void {
+  lines.push(`### ${escapeHeading(task.title)}`);
+  lines.push("");
+  lines.push(`**ID:** \`${task.id}\`  `);
+  lines.push(`**Status:** ${task.status}  `);
+  if (task.owner) {
+    lines.push(`**Owner:** ${escapeInlineText(task.owner)}  `);
+  }
+  lines.push("");
+
+  if (task.description) {
+    lines.push(escapeBlockText(task.description));
+    lines.push("");
+  }
+
+  const blockedBy = bundle.blockedBy.get(task.id) ?? [];
+  if (blockedBy.length > 0) {
+    lines.push("**Blocked by:**");
+    for (const depId of blockedBy) {
+      lines.push(`- \`${depId}\``);
+    }
+    lines.push("");
+  }
+
+  const blocks = bundle.blocks.get(task.id) ?? [];
+  if (blocks.length > 0) {
+    lines.push("**Blocks:**");
+    for (const depId of blocks) {
+      lines.push(`- \`${depId}\``);
+    }
+    lines.push("");
+  }
+
+  const subtasks = bundle.subtasks.filter((s) => s.taskId === task.id);
+  if (subtasks.length > 0) {
+    lines.push("#### Subtasks");
+    lines.push("");
+    for (const subtask of subtasks) {
+      renderSingleSubtask(lines, subtask, bundle);
+    }
+  }
+}
+
+function renderSingleSubtask(lines: string[], subtask: SubtaskRecord, bundle: ExportBundle): void {
+  const statusIcon = subtask.status === "done" ? "x" : " ";
+  lines.push(`- [${statusIcon}] **${escapeInlineText(subtask.title)}** — \`${subtask.id}\` (${subtask.status})`);
+
+  if (subtask.description) {
+    lines.push(formatDescriptionIndented(escapeBlockText(subtask.description), "  "));
+  }
+
+  const blockedBy = bundle.blockedBy.get(subtask.id) ?? [];
+  if (blockedBy.length > 0) {
+    lines.push(`  Blocked by: ${blockedBy.map((id) => `\`${id}\``).join(", ")}`);
+  }
+}
+
+function renderDependencies(lines: string[], bundle: ExportBundle): void {
+  if (bundle.dependencies.length === 0) return;
+
+  lines.push("");
+  lines.push("## Dependencies");
+  lines.push("");
+  lines.push("| Source | Depends on | Type |");
+  lines.push("|--------|------------|------|");
+
+  for (const dep of bundle.dependencies) {
+    const type = dep.internal ? "internal" : "external";
+    lines.push(`| \`${dep.sourceId}\` (${dep.sourceKind}) | \`${dep.dependsOnId}\` (${dep.dependsOnKind}) | ${type} |`);
+  }
+  lines.push("");
+}
+
+function renderExternalNodes(lines: string[], bundle: ExportBundle): void {
+  if (bundle.externalNodes.length === 0) return;
+
+  lines.push("## External nodes");
+  lines.push("");
+  lines.push("These nodes belong to other epics but are referenced by dependencies in this epic.");
+  lines.push("");
+  lines.push("| ID | Kind | Title | Status | Epic ID |");
+  lines.push("|----|------|-------|--------|---------|");
+
+  for (const node of bundle.externalNodes) {
+    const title = node.title !== null ? escapeTableCell(node.title) : "—";
+    lines.push(`| \`${node.id}\` | ${node.kind} | ${title} | ${node.status ?? "—"} | ${node.epicId ?? "—"} |`);
+  }
+  lines.push("");
+}
+
+function renderWarnings(lines: string[], bundle: ExportBundle): void {
+  if (bundle.warnings.length === 0) return;
+
+  lines.push("## Warnings");
+  lines.push("");
+  for (const warning of bundle.warnings) {
+    lines.push(`- **${escapeInlineText(warning.code)}**: ${escapeInlineText(warning.message)}`);
+  }
+  lines.push("");
+}
+
+function renderFooter(lines: string[], bundle: ExportBundle): void {
+  lines.push("---");
+  lines.push("");
+  lines.push(`*Exported from Trekoon on ${new Date(bundle.exportedAt).toISOString()}. This is a snapshot — the database is the source of truth.*`);
+}
+
+function taskAnchor(task: TaskRecord): string {
+  return `task-${task.id}`;
+}

package/src/export/types.ts

@@ -0,0 +1,61 @@
+import type { DependencyRecord, EpicRecord, SubtaskRecord, TaskRecord } from "../domain/types";
+
+export const EXPORT_SCHEMA_VERSION = 1;
+
+export type ExportNodeKind = "task" | "subtask";
+
+export interface ExportDependencyEdge {
+  readonly id: string;
+  readonly sourceId: string;
+  readonly sourceKind: ExportNodeKind;
+  readonly dependsOnId: string;
+  readonly dependsOnKind: ExportNodeKind;
+  readonly internal: boolean;
+}
+
+export interface ExportExternalNode {
+  readonly id: string;
+  readonly kind: ExportNodeKind;
+  readonly title: string | null;
+  readonly status: string | null;
+  readonly epicId: string | null;
+}
+
+export interface ExportWarning {
+  readonly code: string;
+  readonly message: string;
+  readonly entityId?: string;
+}
+
+export interface ExportStatusCounts {
+  readonly total: number;
+  readonly todo: number;
+  readonly inProgress: number;
+  readonly done: number;
+  readonly blocked: number;
+  readonly other: number;
+}
+
+export interface ExportSummary {
+  readonly taskCount: number;
+  readonly subtaskCount: number;
+  readonly dependencyCount: number;
+  readonly externalNodeCount: number;
+  readonly warningCount: number;
+  readonly taskStatuses: ExportStatusCounts;
+  readonly subtaskStatuses: ExportStatusCounts;
+}
+
+export interface ExportBundle {
+  readonly schemaVersion: number;
+  readonly exportedAt: number;
+  readonly epic: EpicRecord;
+  readonly tasks: readonly TaskRecord[];
+  readonly subtasks: readonly SubtaskRecord[];
+  readonly dependencies: readonly ExportDependencyEdge[];
+  readonly externalNodes: readonly ExportExternalNode[];
+  readonly blockedBy: ReadonlyMap<string, readonly string[]>;
+  readonly blocks: ReadonlyMap<string, readonly string[]>;
+  readonly warnings: readonly ExportWarning[];
+  readonly summary: ExportSummary;
+}

package/src/export/write.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, openSync, renameSync, unlinkSync, writeSync, closeSync, constants } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export interface WriteResult {
+  readonly path: string;
+  readonly overwritten: boolean;
+}
+
+export function atomicWrite(options: {
+  readonly path: string;
+  readonly content: string;
+  readonly overwrite: boolean;
+}): WriteResult {
+  const dir = dirname(options.path);
+  mkdirSync(dir, { recursive: true });
+
+  if (options.overwrite) {
+    return writeViaTempRename(options.path, options.content);
+  }
+
+  return writeExclusive(options.path, options.content);
+}
+
+function writeViaTempRename(targetPath: string, content: string): WriteResult {
+  const dir = dirname(targetPath);
+  const tempPath = resolve(dir, `.export-${randomUUID()}.tmp`);
+  let overwritten = false;
+
+  try {
+    // Probe whether the target already exists by attempting an exclusive open.
+    // If it succeeds, the file didn't exist, so we close and remove that probe
+    // since we'll write via temp+rename anyway for atomicity.
+    try {
+      const probeFd = openSync(targetPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+      closeSync(probeFd);
+      unlinkSync(targetPath);
+      overwritten = false;
+    } catch {
+      overwritten = true;
+    }
+
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC);
+    try {
+      writeSync(fd, content);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tempPath, targetPath);
+  } catch (error) {
+    try { unlinkSync(tempPath); } catch { /* best-effort cleanup */ }
+    throw error;
+  }
+
+  return { path: targetPath, overwritten };
+}
+
+function writeExclusive(targetPath: string, content: string): WriteResult {
+  // O_CREAT | O_EXCL is atomic: the kernel fails if the file already exists.
+  let fd: number;
+  try {
+    fd = openSync(targetPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+  } catch (error: unknown) {
+    if (isFileExistsError(error)) {
+      throw new ExportWriteError(
+        `File already exists: ${targetPath}. Use --overwrite to resave.`,
+        "file_exists",
+      );
+    }
+    throw error;
+  }
+
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+
+  return { path: targetPath, overwritten: false };
+}
+
+function isFileExistsError(error: unknown): boolean {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    return (error as { code: string }).code === "EEXIST";
+  }
+  return false;
+}
+
+export class ExportWriteError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "ExportWriteError";
+    this.code = code;
+  }
+}