takt-marp 0.3.0 → 0.4.0

package/README.ja.md

@@ -6,7 +6,7 @@ Marpスライドデッキと、半自動でデッキを生成するためのTAKT
 
 ## TAKT Marp workflow
 
-このworkflowは `slides/<deck>/brief.md` を起点に、`plan`、`compose`、`polish`、`deliver` の状態へ進めます。
+このworkflowは `slides/<deck>/brief.md` を起点に、`plan`、`compose`、`polish`、`deliver` の状態へ進めます。外部調査が必要な deck だけ、任意で先に `research` を実行します。
 
 詳細なworkflow contract: [docs/marp-slide-workflow.md](docs/marp-slide-workflow.md)
 
@@ -34,6 +34,7 @@ Output Requirementsの例:
 ### 2. workflowを実行する
 
 ```bash
+takt-marp research "slides/<deck>"
 takt-marp plan "slides/<deck>"
 takt-marp approve "slides/<deck>" plan --by <name>
 takt-marp compose "slides/<deck>"
@@ -49,6 +50,7 @@ takt-marp plan "slides/<deck>"
 ```
 
 人間承認は `plan` と `compose` に対してのみ `takt-marp approve` で記録します。`review`、`revise`、`qa`、`build-qa` はworkflow内部の責務であり、トップレベルコマンドではありません。
+`research` は `slides/<deck>/research/research-brief.md` を読み、`plan` の必須前提ではありません。
 
 ### 3. 生成されるファイル
 
@@ -59,6 +61,7 @@ slides/<deck>/
   design-system.md
   SLIDES.md
   images/*.svg
+  research/*.md
   review/*.md
 ```
 

package/README.md

@@ -6,7 +6,7 @@ Marp slide decks and a TAKT workflow for semi-automated deck generation.
 
 ## TAKT Marp workflow
 
-The workflow starts from `slides/<deck>/brief.md` and moves through `plan`, `compose`, `polish`, and `deliver`.
+The workflow starts from `slides/<deck>/brief.md` and moves through `plan`, `compose`, `polish`, and `deliver`. Use optional `research` first only when a deck needs external research context.
 
 Detailed workflow contract: [docs/marp-slide-workflow.md](docs/marp-slide-workflow.md)
 
@@ -34,6 +34,7 @@ Example output requirement:
 ### 2. Run the workflows
 
 ```bash
+takt-marp research "slides/<deck>"
 takt-marp plan "slides/<deck>"
 takt-marp approve "slides/<deck>" plan --by <name>
 takt-marp compose "slides/<deck>"
@@ -49,6 +50,7 @@ takt-marp plan "slides/<deck>"
 ```
 
 Human approval is recorded by `takt-marp approve` for `plan` and `compose` only. `review`, `revise`, `qa`, and `build-qa` are internal workflow responsibilities, not top-level commands.
+`research` reads `slides/<deck>/research/research-brief.md` and is not required before `plan`.
 
 ### 3. Generated files
 
@@ -59,6 +61,7 @@ slides/<deck>/
   design-system.md
   SLIDES.md
   images/*.svg
+  research/*.md
   review/*.md
 ```
 

package/fixtures/marp-slide-workflow/_workflow-smoke/brief.md

@@ -1,26 +1,65 @@
-# Brief
+# Workflow Smoke Deck Brief
 
 ## Event
-- Name: Workflow smoke test
-- Date:
-- Duration: 5 minutes
-- Venue: local
-- Audience: maintainer
+- Name: 架空研修ラボ ドメインモデリング講座
+- Date: 2031年4月17日（木）10:00〜16:30
+- Duration: 360 minutes
+- Venue: ミラージュホール A / サンプル配信スタジオ
+- Organizer: サンプル研修ラボ株式会社
+- Audience: メンテナとワークフロー検証者
 
 ## Goal
-Marp slide TAKT workflow が brief から plan、draft、SVG、review、build QA まで接続できることを確認する。
+Marp slide TAKT workflow が、情報量の多い講義ブリーフから normalized brief、reference analysis、coverage matrix、slide blueprint、section source、HTML/CSS visual、SVG visual、review、build QA まで接続できることを確認する。
+
+## Critical Constraints
+- Official Title: 変更に強いドメインモデリングの実践ワークショップ
+- Speaker Name: 山田 サンプル
+- Speaker Affiliation: サンプルデザイン合同会社
+- Design: 白基調だが白黒ではない。カラー印刷を前提に、青・緑・橙・赤を意味づけて使う。
+- Information Density: 投影だけでなく印刷配布テキストとして読める密度を許容する。
+
+### Fixed Outline
+1. 入力を正にする
+（1）briefを保全する
+a. 正式タイトル、講師名、所属を落とさない
+b. 禁止語と避けるべき表現を保持する
+（2）事実を棚卸しする
+a. 架空の日時、主催、形式、対象、場所をFact Inventoryに残す
+b. Target slide countと要求密度の矛盾をfindingにする
+2. 設計をplanへ渡す
+（1）coverage matrixを作る
+a. 固定アウトラインの全leaf項目をslide IDへ対応させる
+b. 未対応項目はneeds_inputではなくPlan Findingsへ残す
+（2）visual strategyを決める
+a. カード、比較、表、軽量フローはhtml:で構成する
+b. 座標制御や複雑な矢印だけsvg:またはinline-svg:にする
+3. section sourceからassembleする
+（1）blueprintを分ける
+a. slide-blueprint.mdにcontent atomsとsection manifestを残す
+b. sections/*.mdからSLIDES.mdへassembleする
+（2）deliveryを検証する
+a. HTMLとPDFをbuildできることを確認する
+b. generated artifactをsource artifactへ混ぜない
 
 ## Core Message
-半自動のMarp生成workflowは、入力、構成、visual、レビュー、QAを分離すると安定する。
+半自動のMarp生成workflowは、入力、coverage、blueprint、section source、visual、レビュー、QAを分離すると安定する。
 
 ## Audience Context
 聴衆はこのリポジトリのメンテナであり、TAKTとMarpの基本を理解している。
 
 ## Required Topics
-- briefを入力の正にする
-- SVG-firstで図を管理する
-- plan後とdraft後に人間確認を挟む
-- build QAまでworkflowに含める
+- 1. 入力を正にする > （1）briefを保全する > a. 正式タイトル、講師名、所属を落とさない
+- 1. 入力を正にする > （1）briefを保全する > b. 禁止語と避けるべき表現を保持する
+- 1. 入力を正にする > （2）事実を棚卸しする > a. 架空の日時、主催、形式、対象、場所をFact Inventoryに残す
+- 1. 入力を正にする > （2）事実を棚卸しする > b. Target slide countと要求密度の矛盾をfindingにする
+- 2. 設計をplanへ渡す > （1）coverage matrixを作る > a. 固定アウトラインの全leaf項目をslide IDへ対応させる
+- 2. 設計をplanへ渡す > （1）coverage matrixを作る > b. 未対応項目はneeds_inputではなくPlan Findingsへ残す
+- 2. 設計をplanへ渡す > （2）visual strategyを決める > a. カード、比較、表、軽量フローはhtml:で構成する
+- 2. 設計をplanへ渡す > （2）visual strategyを決める > b. 座標制御や複雑な矢印だけsvg:またはinline-svg:にする
+- 3. section sourceからassembleする > （1）blueprintを分ける > a. slide-blueprint.mdにcontent atomsとsection manifestを残す
+- 3. section sourceからassembleする > （1）blueprintを分ける > b. sections/*.mdからSLIDES.mdへassembleする
+- 3. section sourceからassembleする > （2）deliveryを検証する > a. HTMLとPDFをbuildできることを確認する
+- 3. section sourceからassembleする > （2）deliveryを検証する > b. generated artifactをsource artifactへ混ぜない
 
 ## Optional Topics
 - appendixは必要な場合だけ作る
@@ -29,16 +68,63 @@ Marp slide TAKT workflow が brief から plan、draft、SVG、review、build QA
 - Web画像の自動取得
 - 他deck画像の自動流用
 - 長い本文をスライドに詰め込むこと
+- SVG-firstという方針に戻すこと
+- htmlで十分なカード、比較、表、軽量フローをSVG化すること
+- サンプル主催名、架空日付、架空場所を実在情報に置き換えること
 
 ## Source Materials
 - docs/marp-slide-workflow.md
+- _workflow-smoke internal synthetic brief only
 
 ## Speaker Notes
-短い確認用deckなので、各スライドのnotesは2-3文でよい。
+短い確認用deckなので、各スライドのnotesは2-3文でよい。Durationが分単位で指定されているため、notesには尺マーカーを付ける。
 
 ## Output Requirements
 - Format: Marp
 - Language: Japanese
 - Target slide count: 5
+- Deck Mode: overview
 - Deliverables: html, pdf
-- Visual scope: use exactly one SVG for the workflow overview slide. For paired discipline slides, use text-only split columns with Visual: none; do not plan unused SVG placeholders.
+- Slide Count Consistency Scenario: Target slide count: 5 は概要版として扱う。講義本体を要求する場合は100〜140または期待値相当へ修正する必要がある、というPlan Findingを作れること。
+- Visual scope: html: cards/comparison/table/light-flow を優先し、座標制御が必要な1箇所だけ inline-svg: を使う。未使用SVG placeholderを計画しない。
+
+## Fact Inventory
+- 主催: サンプル研修ラボ株式会社
+- 形式: ミラージュホール A / サンプル配信スタジオ
+- 日時: 2031年4月17日（木）10:00〜16:30
+- 対象: メンテナとワークフロー検証者
+- 場所: ミラージュホール A
+- 講師所属: サンプルデザイン合同会社
+
+## Terminology Policy
+- Domain-Driven Design はドメイン駆動設計と表記する。
+- Workflow は workflow と英字表記で統一する。
+- Fixed Outline の語句は言い換えない。
+
+## Example Policy
+- 共通題材は「備品購入申請・承認」とし、章をまたいで一貫利用する。
+
+## Code Example Policy
+- Java風の疑似コードでBefore / Afterを示す。
+- 業務の意味がコード構造へ表れることを示す。
+- フレームワーク固有APIへ寄せすぎない。
+
+## Exercise Policy
+- 短時間の個人演習にする。
+- 模範回答または解説を巻末またはnotesに残す。
+
+## Appendix Requirements
+- 用語集
+- 実践チェックリスト
+- 演習模範回答
+
+## Quality Checklist
+- 正式タイトル完全一致
+- 講師所属がサンプルデザイン合同会社
+- 禁止語を使わない
+- 固定アウトラインを変更しない
+- 白基調だが白黒ではない
+- coverage matrixに全leaf項目がある
+- html: visual と svg:/inline-svg: visual の責務が分かれている
+- sections/*.mdからSLIDES.mdへassembleできる
+- build:html / build:pdf が成功する

package/fixtures/marp-slide-workflow/_workflow-smoke/research/research-brief.md

@@ -0,0 +1,12 @@
+# Workflow Smoke Research Brief
+
+## Research Goal
+Validate that the optional research command can synchronize built-in deep research output into deck-local research artifacts before planning.
+
+## Scope
+- Use only deterministic mock research content.
+- Preserve missing source URL, retrieval time, confidence, and claim-source mapping as absent information.
+- Do not infer or supplement facts that are not present in the built-in research report.
+
+## Expected Consumer
+The subsequent plan command may read the generated research artifacts as optional context, while still using `brief.md` as the primary input.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takt-marp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "takt-marp",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
     "node": ">=24"
   },
   "scripts": {
+    "slide:research": "node scripts/takt-marp-run-slide-workflow.mjs research",
     "slide:plan": "node scripts/takt-marp-run-slide-workflow.mjs plan",
     "slide:compose": "node scripts/takt-marp-run-slide-workflow.mjs compose",
     "slide:polish": "node scripts/takt-marp-run-slide-workflow.mjs polish",
@@ -29,12 +30,14 @@
     "slide:render-evidence": "node scripts/takt-marp-render-slide-workflow-evidence.mjs",
     "slide:validate-foundation": "node scripts/takt-marp-validate-slide-workflow-foundation.mjs",
     "slide:smoke": "node scripts/takt-marp-validate-slide-workflow-smoke.mjs",
-    "test": "npm run slide:validate-foundation",
+    "test": "npm run slide:validate-foundation && npm run slide:smoke -- --provider mock",
     "build": "npm run build:html && npm run build:pdf",
     "build:html": "node scripts/takt-marp-build-slide-artifact.mjs html",
     "build:pptx": "node scripts/takt-marp-build-slide-artifact.mjs pptx",
     "build:pdf": "node scripts/takt-marp-build-slide-artifact.mjs pdf",
     "preview": "node scripts/takt-marp-preview-slide.mjs takt-sdd",
+    "installer:ci": "npm run slide:validate-foundation && npm run installer:check-templates && npm run installer:check-package && npm run installer:validate && npm run slide:smoke -- --provider mock",
+    "installer:check-ci": "node scripts/takt-marp-validate-installer-ci-entrypoint.mjs",
     "installer:sync-templates": "node scripts/takt-marp-sync-project-templates.mjs --write",
     "installer:check-templates": "node scripts/takt-marp-sync-project-templates.mjs",
     "installer:check-package": "node scripts/takt-marp-validate-package-boundary.mjs",

package/scripts/lib/takt-marp-cli.mjs

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { statSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { initializeProject } from "./takt-marp-project-init.mjs";
+import { ejectProject } from "./takt-marp-project-eject.mjs";
+import { resolveTemplateSource, workflowFilePath } from "./takt-marp-project-templates.mjs";
 import { packageScriptPath } from "./takt-marp-runtime-context.mjs";
 import {
   APPROVAL_COMMANDS,
@@ -12,20 +12,20 @@ import {
   SlideWorkflowError,
 } from "./takt-marp-slide-workflow.mjs";
 
-const WORKFLOW_COMMANDS = ["plan", "compose", "polish", "deliver"];
+const RESEARCH_COMMANDS = ["research"];
+const WORKFLOW_COMMANDS = [...RESEARCH_COMMANDS, "plan", "compose", "polish", "deliver"];
 const BUILD_COMMANDS = Object.freeze({
   "build:html": "html",
   "build:pdf": "pdf",
   "build:pptx": "pptx",
 });
 const UTILITY_COMMANDS = [...Object.keys(BUILD_COMMANDS), "preview"];
-const VALID_COMMANDS = ["init", ...WORKFLOW_COMMANDS, ...UTILITY_COMMANDS, "approve", "smoke"];
+const VALID_COMMANDS = ["eject", ...WORKFLOW_COMMANDS, "approve", "smoke", ...UTILITY_COMMANDS];
 const RUNNER_SCRIPT = "scripts/takt-marp-run-slide-workflow.mjs";
 const APPROVE_SCRIPT = "scripts/takt-marp-approve-slide-workflow-state.mjs";
 const SMOKE_SCRIPT = "scripts/takt-marp-validate-slide-workflow-smoke.mjs";
 const BUILD_SCRIPT = "scripts/takt-marp-build-slide-artifact.mjs";
 const PREVIEW_SCRIPT = "scripts/takt-marp-preview-slide.mjs";
-const REQUIRED_PROJECT_DIRS = [".takt/workflows", ".takt/facets"];
 const FORWARDED_SIGNALS = new Set(["SIGINT", "SIGTERM"]);
 
 function usage() {
@@ -33,11 +33,15 @@ function usage() {
     "Usage: takt-marp <command> [arguments]",
     "",
     "Commands:",
-    "  init [dir] [--force|--overwrite]  Install .takt/workflows and .takt/facets templates into <dir> (default: .)",
+    "  eject [dir] [--force|--overwrite] Copy .takt/workflows and .takt/facets templates into <dir> (default: .)",
+    "  research <slides/deck> [options] Optional pre-research command before slide planning",
     "  plan <slides/deck> [options]      Run the plan workflow for a deck in the current project",
     "  compose <slides/deck> [options]   Run the compose workflow for a deck in the current project",
     "  polish <slides/deck> [options]    Run the polish workflow for a deck in the current project",
     "  deliver <slides/deck> [options]   Run the deliver workflow for a deck in the current project",
+    "  approve <slides/deck> <command> --by <name> [--force]",
+    "                                    Approve a workflow state (command: plan or compose)",
+    "  smoke [--provider <name>]         Run smoke validation in a temporary project (default provider: mock)",
     "  build:html [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
     "                                    Build HTML artifact without changing workflow state",
     "  build:pdf [deck|slides/<deck>|slides/<deck>/SLIDES.md]",
@@ -46,9 +50,6 @@ function usage() {
     "                                    Build PPTX artifact without changing workflow state",
     "  preview <deck|slides/<deck>|slides/<deck>/SLIDES.md>",
     "                                    Start Marp server mode without changing workflow state",
-    "  approve <slides/deck> <command> --by <name> [--force]",
-    "                                    Approve a workflow state (command: plan or compose)",
-    "  smoke [--provider <name>]         Run smoke validation in a temporary project (default provider: mock)",
     "",
     "Workflow options (passed through to the workflow runner unchanged):",
     "  --force            Invalidate an already-successful state and rerun",
@@ -56,11 +57,11 @@ function usage() {
   ].join("\n");
 }
 
-function initUsage() {
+function ejectUsage() {
   return [
-    "Usage: takt-marp init [dir] [--force|--overwrite]",
+    "Usage: takt-marp eject [dir] [--force|--overwrite]",
     "",
-    "Installs .takt/workflows/** and .takt/facets/** templates into <dir> (default: current directory).",
+    "Copies .takt/workflows/** and .takt/facets/** templates into <dir> (default: current directory).",
     "",
     "Options:",
     "  --force      Overwrite existing template-owned files",
@@ -69,24 +70,6 @@ function initUsage() {
   ].join("\n");
 }
 
-function isDirectory(candidatePath) {
-  const stats = statSync(candidatePath, { throwIfNoEntry: false });
-  return stats !== undefined && stats.isDirectory();
-}
-
-function assertProjectInitialized() {
-  const cwd = process.cwd();
-  const missing = REQUIRED_PROJECT_DIRS.filter(
-    (relative) => !isDirectory(path.join(cwd, ...relative.split("/"))),
-  );
-  if (missing.length > 0) {
-    throw new SlideWorkflowError(
-      `Target project is not initialized: missing ${missing.join(" and ")} in ${cwd}. Run 'takt-marp init .' first.`,
-      "PROJECT_NOT_INITIALIZED",
-    );
-  }
-}
-
 function runPackageScript(relativeScriptPath, args, options = {}) {
   return new Promise((resolve, reject) => {
     let stopping = false;
@@ -128,8 +111,9 @@ function runPackageScript(relativeScriptPath, args, options = {}) {
 }
 
 async function runWorkflowCommand(command, args) {
-  assertProjectInitialized();
-  return runPackageScript(RUNNER_SCRIPT, [command, ...args]);
+  const source = resolveTemplateSource({ projectRoot: process.cwd() });
+  const selectedWorkflowFilePath = workflowFilePath(source, command);
+  return runPackageScript(RUNNER_SCRIPT, [command, ...args, "--workflow-file", selectedWorkflowFilePath]);
 }
 
 async function runBuildCommand(command, args) {
@@ -140,7 +124,7 @@ async function runPreview(args) {
   return runPackageScript(PREVIEW_SCRIPT, args, { successOnSignal: true });
 }
 
-async function runInit(args) {
+async function runEject(args) {
   let parsed;
   try {
     parsed = parseArgs({
@@ -154,26 +138,26 @@ async function runInit(args) {
     });
   } catch (error) {
     throw new SlideWorkflowError(
-      `Invalid init arguments: ${error.message}. Run 'takt-marp init --help' for usage.`,
+      `Invalid eject arguments: ${error.message}. Run 'takt-marp eject --help' for usage.`,
       "INVALID_ARGS",
     );
   }
   if (parsed.values.help) {
-    console.log(initUsage());
+    console.log(ejectUsage());
     return 0;
   }
   if (parsed.positionals.length > 1) {
     throw new SlideWorkflowError(
-      `Unexpected extra init arguments: ${parsed.positionals.slice(1).join(" ")}. Run 'takt-marp init --help' for usage.`,
+      `Unexpected extra eject arguments: ${parsed.positionals.slice(1).join(" ")}. Run 'takt-marp eject --help' for usage.`,
       "INVALID_ARGS",
     );
   }
 
   const targetDir = path.resolve(process.cwd(), parsed.positionals[0] ?? ".");
   const force = parsed.values.force || parsed.values.overwrite;
-  const { created, overwritten } = await initializeProject({ targetDir, force });
+  const { created, overwritten } = await ejectProject({ targetDir, force });
 
-  const lines = [`Initialized takt-marp templates in ${targetDir}`];
+  const lines = [`Ejected takt-marp templates in ${targetDir}`];
   lines.push(`Created ${created.length} file(s)${created.length > 0 ? ":" : "."}`);
   for (const relativePath of created) {
     lines.push(`  ${relativePath}`);
@@ -189,7 +173,7 @@ async function runInit(args) {
     "Next steps:",
     "  - Provider configuration stays under your ownership: takt-marp does not create or modify",
     "    TAKT provider settings, API keys, or credentials.",
-    "  - Configure your TAKT provider before running workflows.",
+    "  - Edit ejected workflow/facet templates only when you need project-local customization.",
     `  - Run a workflow from the project root, e.g.: takt-marp plan slides/<deck>`,
   );
   console.log(lines.join("\n"));
@@ -198,8 +182,8 @@ async function runInit(args) {
 
 async function runSmoke(args) {
   // Smoke runs in a freshly created temporary project so the user's current
-  // project is never touched. The temp project is retained after the run as
-  // the home of the provider-specific smoke summaries.
+  // project is never touched. Template source selection stays no-copy by
+  // default; only the smoke validator may create smoke deck artifacts.
   let tempProject;
   try {
     tempProject = await mkdtemp(path.join(os.tmpdir(), "takt-marp-smoke-"));
@@ -209,7 +193,6 @@ async function runSmoke(args) {
       "SMOKE_PREPARE_FAILED",
     );
   }
-  await initializeProject({ targetDir: tempProject, force: false });
   console.log(`Temporary smoke project: ${tempProject}`);
 
   // Pass argv through unchanged: provider selection (--provider) and the
@@ -265,7 +248,6 @@ async function runApprove(args) {
     console.log(approveUsage());
     return 0;
   }
-  assertProjectInitialized();
   if (parsed.positionals.length !== 2) {
     throw new SlideWorkflowError(
       `Expected <slides/deck> and <command>. Run 'takt-marp approve --help' for usage.`,
@@ -294,14 +276,20 @@ export async function runCli(argv) {
   }
 
   try {
+    if (command === "init") {
+      throw new SlideWorkflowError(
+        "`init` has been removed. Use `takt-marp eject .` to copy template assets.",
+        "COMMAND_REMOVED",
+      );
+    }
     if (!VALID_COMMANDS.includes(command)) {
       throw new SlideWorkflowError(
         `'${command}' is not a takt-marp command. Valid commands: ${VALID_COMMANDS.join(", ")}. Run 'takt-marp --help' for usage.`,
         "UNKNOWN_COMMAND",
       );
     }
-    if (command === "init") {
-      return await runInit(rest);
+    if (command === "eject") {
+      return await runEject(rest);
     }
     if (command === "approve") {
       return await runApprove(rest);

package/scripts/lib/takt-marp-errors.mjs

@@ -0,0 +1,11 @@
+export class SlideWorkflowError extends Error {
+  constructor(message, code = "SLIDE_WORKFLOW_ERROR") {
+    super(message);
+    this.name = "SlideWorkflowError";
+    this.code = code;
+  }
+}
+
+export function formatError(error) {
+  return error instanceof SlideWorkflowError ? `${error.code}: ${error.message}` : String(error?.stack ?? error);
+}

package/scripts/lib/takt-marp-project-eject.mjs

@@ -0,0 +1,136 @@
+import { copyFile, lstat, mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { SlideWorkflowError } from "./takt-marp-errors.mjs";
+import { assertNoProhibitedEntries, listTemplateEntries } from "./takt-marp-project-templates.mjs";
+
+const TAKT_DIR = ".takt";
+
+async function assertTargetDirectory(targetDir) {
+  if (!path.isAbsolute(targetDir)) {
+    throw new SlideWorkflowError(
+      `Target directory must be an absolute path: ${targetDir}`,
+      "TARGET_DIR_NOT_FOUND",
+    );
+  }
+
+  let stats;
+  try {
+    stats = await stat(targetDir);
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+      throw new SlideWorkflowError(
+        `Target directory does not exist: ${targetDir}`,
+        "TARGET_DIR_NOT_FOUND",
+      );
+    }
+    throw error;
+  }
+
+  if (!stats.isDirectory()) {
+    throw new SlideWorkflowError(
+      `Target path is not a directory: ${targetDir}`,
+      "TARGET_DIR_NOT_FOUND",
+    );
+  }
+}
+
+async function readOptionalStats(filePath) {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function templateDestination(targetDir, relativePath) {
+  return path.join(targetDir, TAKT_DIR, ...relativePath.split("/"));
+}
+
+function templateResultPath(relativePath) {
+  return `${TAKT_DIR}/${relativePath}`;
+}
+
+async function inspectDestination(targetDir, relativePath) {
+  const relativeParts = [TAKT_DIR, ...relativePath.split("/")];
+  for (let index = 1; index < relativeParts.length; index += 1) {
+    const ancestorParts = relativeParts.slice(0, index);
+    const ancestorPath = path.join(targetDir, ...ancestorParts);
+    const stats = await readOptionalStats(ancestorPath);
+    if (!stats) {
+      return { exists: false };
+    }
+    if (!stats.isDirectory()) {
+      return { exists: false, conflictPath: ancestorParts.join("/") };
+    }
+  }
+
+  const destinationPath = path.join(targetDir, ...relativeParts);
+  const stats = await readOptionalStats(destinationPath);
+  if (!stats) {
+    return { exists: false };
+  }
+  if (!stats.isFile()) {
+    return { exists: false, conflictPath: relativeParts.join("/") };
+  }
+  return { exists: true };
+}
+
+function pushUnique(items, item) {
+  if (!items.includes(item)) {
+    items.push(item);
+  }
+}
+
+function createEjectConflict(conflicts) {
+  const error = new SlideWorkflowError(
+    `Eject conflict: existing template files would be overwritten. Conflicting paths:\n${conflicts.join("\n")}\nRe-run with --force (or --overwrite) to overwrite template-owned paths.`,
+    "EJECT_CONFLICT",
+  );
+  error.conflicts = conflicts;
+  return error;
+}
+
+export async function ejectProject(options) {
+  const { targetDir, force = false } = options;
+  await assertTargetDirectory(targetDir);
+
+  const entries = await listTemplateEntries();
+  assertNoProhibitedEntries(entries);
+
+  const plan = [];
+  for (const entry of entries) {
+    const destinationRelativePath = templateResultPath(entry.relativePath);
+    const destinationPath = templateDestination(targetDir, entry.relativePath);
+    const destinationState = await inspectDestination(targetDir, entry.relativePath);
+    plan.push({ entry, destinationRelativePath, destinationPath, ...destinationState });
+  }
+
+  const conflicts = [];
+  for (const item of plan) {
+    if (item.conflictPath) {
+      pushUnique(conflicts, item.conflictPath);
+    } else if (!force && item.exists) {
+      pushUnique(conflicts, item.destinationRelativePath);
+    }
+  }
+  if (conflicts.length > 0) {
+    throw createEjectConflict(conflicts);
+  }
+
+  const created = [];
+  const overwritten = [];
+  for (const item of plan) {
+    await mkdir(path.dirname(item.destinationPath), { recursive: true });
+    await copyFile(item.entry.sourcePath, item.destinationPath);
+    if (item.exists) {
+      overwritten.push(item.destinationRelativePath);
+    } else {
+      created.push(item.destinationRelativePath);
+    }
+  }
+
+  return { created, overwritten };
+}