@warnyin/agents 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -23,6 +23,19 @@
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-06-11
+
+### Added
+- **DESIGN sizing gate — establish tier ก่อนจ่าย ceremony** (เสริม feature `change-sizing`) — เพิ่ม **step 1.5 "Establish tier"** ใน `src/.warnyin/workflow/stages/design.md §4` (ก่อน `business.md`/`proposal`): DESIGN **ประเมินขนาด change เบื้องต้นเอง** ตาม rubric (`triage.md` signals + hard-floor) → **มั่นใจ = กำหนด tier + บันทึก `proposal.md`**; **ไม่มั่นใจ/ก้ำกึ่ง = ถาม user เป็น options** (ประเมินด้วย `/warnyin:triage` ก่อน / user กำหนด tier เองถ้ารู้; ก้ำกึ่ง default = ปัดขึ้น `standard`); **hard-floor** (auth/migration/secret/public-API/security-sensitive) บังคับ ≥ standard เสมอ. อุดช่องว่างเดิมที่ `§7` **บริโภค** tier แต่ไม่มีตัวการันตีว่า established จริง (DESIGN เคยเดินโดยไม่รู้ขนาด). `§7` เพิ่มประโยคชี้ "tier ถูก established ที่ §4 step 1.5" (ไม่ inline rubric — ชี้ `triage.md`); ปรับช่อง `ขนาด` ใน proposal template `เล็ก/กลาง/ใหญ่` → `fast/standard/large` (vocab ตรง triage). tier = judgment (⚠ ไม่ใช่ validator). payload ติดมากับ `--update` รอบถัดไป
+
+### Fixed
+- **`docs/features/global-install/spec.md`** — เพิ่ม `WHEN` ที่ขาดใน scenario "--global + --project → error" (validate-topic C5)
+
+## [0.13.0] - 2026-06-11
+
+### Added
+- **Global install mode — ติดตั้งครั้งเดียวใช้ได้ทุกโปรเจกต์ (opt-in)** (feature `global-install`) — `npx @warnyin/agents --global` ติดตั้ง adapter → `~/.claude/{commands/warnyin,agents,skills}` + playbook → `~/.warnyin/{workflow,template}` **ครั้งเดียว** → `/warnyin:*` ใช้ได้ทุกโปรเจกต์ (Claude Code โหลด user-level `~/.claude/`). **Hybrid:** workspace (`docs/`) ยัง per-project; โปรเจกต์ที่มี `./.warnyin/` local → ใช้ local ก่อน (override → คง reproducibility); **per-project ยังเป็น default**. **mode resolution** `resolveMode()` (pure-fn): flag `--global`/`--project`; ไม่ระบุ+TTY → prompt; **non-TTY → project (CI-safe ไม่ค้าง)**; `--global --project` → error. **ปลอดภัยต่อ homedir:** first-install `overwrite:false` (ไม่ทับไฟล์ user ใน `~/.claude/{agents,skills}`), `installGlobalNote()` เขียน `~/.claude/CLAUDE.md` แบบ **append-with-marker** (ไม่แตะ personal global memory), homedir guard (falsy/root → error), echo target paths. **resolve playbook local-first → global** ผ่าน convention canonical ใน `CLAUDE.md`/`AGENTS.md`/`CLAUDE.global.md` (ไม่ duplicate ลงทุก adapter). `/warnyin:init` รับ workspace bootstrap (scaffold + seed `docs/`, อ่าน template local→global). **backward compatible** (project mode = default ไม่เปลี่ยน; `--global` opt-in). **limitation:** Codex/Antigravity global root doc รอบนี้ยังไม่รองรับ (per-project ใช้ได้เต็ม). zero-dep + cross-platform (`os.homedir()`, HOME/USERPROFILE); payload ติดมากับ `--update` รอบถัดไป
+
 ## [0.12.0] - 2026-06-11
 
 ### Added

package/README.md

@@ -18,12 +18,24 @@ Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶
 
 ```bash
 cd my-project
-npx @warnyin/agents             # ติดตั้ง (ข้ามไฟล์ที่มีอยู่ ไม่เขียนทับ)
+npx @warnyin/agents             # ติดตั้งลงโปรเจกต์นี้ (ข้ามไฟล์ที่มีอยู่ ไม่เขียนทับ)
 npx @warnyin/agents --dry-run   # ดูก่อนว่าจะสร้างอะไร
 npx @warnyin/agents --update    # อัปเดต playbook กลางเป็นเวอร์ชันล่าสุด
 # ทางสำรอง (ดึงตรงจาก main): npx github:warnyin/warnyin-agents
 ```
 
+**ติดตั้งแบบ global (ใช้ได้ทุกโปรเจกต์ — ติดตั้งครั้งเดียว):**
+
+```bash
+npx @warnyin/agents --global    # ลง ~/.claude + ~/.warnyin → /warnyin:* ใช้ได้ทุกโปรเจกต์
+npx @warnyin/agents --project   # บังคับลงโปรเจกต์ (ไม่ถาม)
+# ไม่ระบุ flag: ถ้าเป็น terminal จะถามให้เลือก; ถ้า non-TTY (CI/pipe) → ลงโปรเจกต์อัตโนมัติ
+```
+
+- **global vs project:** `--project` (ค่าเริ่มต้น) = ติดตั้ง vendored ลง repo (commit ลง git ได้ → ทีม share เวอร์ชันเป๊ะ); `--global` = ติดตั้งครั้งเดียวที่ `~/` ใช้ทุกโปรเจกต์ (สะดวกสำหรับคนทำหลาย repo)
+- **global เป็น Hybrid:** โปรเจกต์ที่มี `.warnyin/` ของตัวเอง (local) → ใช้ local ก่อนเสมอ (override global); workspace (`docs/`) ยังแยกต่อโปรเจกต์ — รัน `/warnyin:init` ครั้งแรกในแต่ละโปรเจกต์
+- **global ปลอดภัยต่อ `~/`:** ไม่ทับไฟล์ที่มีอยู่ของคุณใน `~/.claude/` (เขียนทับเฉพาะ `--update`), แสดง path ที่จะเขียนก่อน
+- _(global รองรับ Claude Code; Codex/Antigravity ใช้ติดตั้งแบบ per-project)_
 - โปรเจกต์ที่มี `CLAUDE.md` / `AGENTS.md` อยู่แล้ว → installer **ต่อท้ายเป็น section** ไม่เขียนทับ
 - `--update` เขียนทับเฉพาะ core (`.warnyin/workflow/`, `.claude/commands/warnyin/`, template ใน `.warnyin/template/`) — ไม่แตะ `docs/` และงานจริง
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warnyin/agents",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Warnyin Standard Workflow installer — 5-stage ways of work (Discovery/DESIGN/BUILD/VERIFY/SHIP) สำหรับทุกโปรเจกต์",
   "type": "module",
   "license": "MIT",

package/src/.warnyin/installer/templates/CLAUDE.global.md

@@ -0,0 +1,5 @@
+<!-- warnyin:global-note -->
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)

package/src/.warnyin/installer/templates/CLAUDE.md

@@ -28,3 +28,7 @@ Claude Code อ่าน `.claude/` + ไฟล์นี้, ส่วน Codex/
 
 ## อัปเดต workflow
 `npx @warnyin/agents --update` — เขียนทับเฉพาะ playbook กลาง (`.warnyin/workflow/`, `.claude/commands/warnyin/`, template `.warnyin/template/stages/[topic]/`) ไม่แตะ `docs/` และงานจริงใน `docs/stages/`
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)

package/src/.warnyin/template/stages/[topic]/proposal.md

@@ -7,7 +7,7 @@
 |---|---|
 | **Slug** | `<kebab-case>` |
 | **ประเภท** | `feature` / `bugfix` / `refactor` / `docs` |
-| **ขนาด** | `เล็ก` / `กลาง` / `ใหญ่` |
+| **ขนาด** | `fast` / `standard` / `large` (จาก triage หรือ ประเมินใน DESIGN step 1.5) |
 | **วันที่** | `YYYY-MM-DD` |
 | **มาจาก Discovery?** | `./discovery.md` หรือ `ไม่มี` |
 

package/src/.warnyin/workflow/init.md

@@ -31,6 +31,16 @@
 
 ## 3. ลำดับขั้นการทำงาน (process)
 
+0. **Workspace bootstrap (ทำก่อนวิเคราะห์โปรเจกต์ — idempotent):**
+   - **หา template:** ตรวจ `./.warnyin/template/` ก่อน (local) — ไม่มีหรือไม่มี `./.warnyin/` → fallback `~/.warnyin/template/` (global install); ใช้ path ที่พบเป็น `<template>`
+   - **สร้าง scaffold (ถ้ายังไม่มี):**
+     - `docs/stages/context.md` — ไม่มีให้สร้างไฟล์เปล่า; มีอยู่แล้ว → ข้าม
+     - `docs/stages/achieved/.gitkeep` — ไม่มีให้สร้างไฟล์เปล่า (สร้าง dir `docs/stages/achieved/` ด้วยถ้าจำเป็น); มีอยู่แล้ว → ข้าม
+   - **seed `docs/` จาก `<template>/docs/**` (ถ้า template มี):**
+     - วน entry ใน `<template>/docs/` — **ข้าม entry ที่ชื่อขึ้นต้นด้วย `[`** (placeholder เช่น `[component]/`, `[topic]/` — seedDocs-skip invariant)
+     - entry ที่เหลือ: ปลายทาง `docs/<entry>` — **ไม่ทับไฟล์ที่มีอยู่แล้ว** (copy เฉพาะที่ยังไม่มี)
+   - **ทั้งหมดนี้เป็น agent-driven** — agent ตรวจ/สร้างไฟล์เปล่าเอง; ไม่ต้องรัน script
+
 1. **สแกนภาพรวม:** โครงสร้าง repo, package manifest, ภาษา/framework, แบ่งเป็น **component** อะไรบ้าง (เช่น api-service, admin-console)
 2. **วิเคราะห์ลึกต่อ component (ขนานได้, read-only):** โครงสร้างโฟลเดอร์/โมดูล, pattern/convention ที่ใช้จริงในโค้ด, วิธี build/test ที่มีอยู่
 3. **วิเคราะห์ infra:** docker/compose, env, service ที่ต้องรันสำหรับ local dev
@@ -44,7 +54,7 @@
 5. **เสนอ summary → user ยืนยันครั้งเดียว**
 6. **เขียนไฟล์จริงลง `docs/` ให้ครบตาราง §4 (ขั้นบังคับ ห้ามข้าม)** — ทำตามกลไก 6.1–6.4 นี้:
 
-   **6.1 ไฟล์ root** — copy template แล้วเติม:
+   **6.1 ไฟล์ root** — copy template แล้วเติม (ขั้นนี้ = เติมเนื้อหาหลังวิเคราะห์ เสริมขั้น 0 ที่สร้าง scaffold/seed ไว้แล้ว):
    ```
    mkdir -p docs
    cp .warnyin/template/docs/project.md         docs/project.md
@@ -52,6 +62,7 @@
    cp .warnyin/template/docs/rule.md            docs/rule.md
    cp .warnyin/template/docs/troubleshooting.md docs/troubleshooting.md
    ```
+   - ใช้ `.warnyin/template/` (local) — per-project install มีให้เสมอ; global mode ขั้น 0 seed ให้แล้ว (template อ่าน local→global ตามขั้น 0)
    - ไฟล์ไหนมีอยู่แล้วใน `docs/` → **ห้าม `cp` ทับ** ให้เปิดอ่านแล้ว Edit เติมแทน
    - `project.md` → เติมจากผลสัมภาษณ์ user (ข้อ 4) · `infra.md` → เติมจาก config จริง (ข้อ 3) · `rule.md`/`troubleshooting.md` → วางโครงหัวข้อ ใส่ `<!-- ยังว่าง รอเติม -->` ในส่วนที่ยังไม่มีข้อมูล
 

package/src/.warnyin/workflow/stages/design.md

@@ -49,6 +49,11 @@
 
 1. **เตรียมพื้นที่:** ใช้/สร้างโฟลเดอร์ `docs/stages/<slug>/` (ถ้ามาจาก Discovery ใช้อันเดิม)
 2. **Ground + เคลียร์ความไม่ชัด:** อ่าน Input; ทุกจุดกำกวมเรื่อง design → ถามทีละข้อ + recommended answer จนชัด (ถ้าใหญ่/ไม่ชัดมาก → แนะนำ Discovery ก่อน)
+1.5 **Establish tier (ก่อนจ่าย ceremony):** ประเมินขนาด change เบื้องต้นตาม rubric (`triage.md` §2 — signals + hard-floor)
+   - **มั่นใจ** → กำหนด tier + บันทึก `proposal.md` ช่อง `ขนาด`
+   - **ไม่มั่นใจ/ก้ำกึ่ง** → ถาม user (options): (ก) ประเมินด้วย `/warnyin:triage` ก่อน · (ข) user กำหนด tier เองถ้ารู้  [ก้ำกึ่ง default = ปัดขึ้น standard]
+   - **hard-floor** (auth/migration/secret/public-API/security-sensitive) → ≥ standard เสมอ
+   - tier → drive ceremony ตาม §7
 3. **business.md** *(optional — ข้ามได้ถ้า change เล็ก เช่น fix bug นิดหน่อย)*: what & why เชิงธุรกิจ — goal, คุณค่า, persona, success metric
 4. **proposal.md** (what & why): สรุป change ที่จะทำ, เหตุผล, ทางเลือกที่พิจารณา/ตัดทิ้ง, scope in/out
 5. **design.md** (how): ออกแบบเชิงเทคนิคแบบ vertical slice — slice มีอะไรบ้าง, แต่ละ slice ตัดผ่าน layer ไหน, data model, interface/contract, flow, ผลกระทบต่อระบบเดิม (ใช้ lens `.warnyin/workflow/roles/sa.md`) — **ครอบ "Spec delta" ด้วย**: เทียบพฤติกรรมที่ change นี้แตะกับ `docs/features/<name>/spec.md` ปัจจุบัน แล้วเขียน ADDED/MODIFIED/REMOVED (SHIP merge ตามนี้); change ไม่แตะพฤติกรรม feature → ระบุ "ไม่มี delta"
@@ -105,7 +110,9 @@
 
 ## 7. ปรับความละเอียดตามขนาด change (3-tier)
 
-ปรับ ceremony ตาม **tier** ที่ `/warnyin:triage` ประเมิน (`.warnyin/workflow/triage.md`) — fast/standard/large:
+**tier ถูก established ที่ §4 step 1.5** (ประเมินเอง / มั่นใจกำหนด / ไม่มั่นใจถาม options / hard-floor บังคับ ≥ standard) — ส่วน §7 นี้อธิบาย ceremony ที่ drive โดย tier ที่ established
+
+ปรับ ceremony ตาม **tier** (canonical rubric ดู `.warnyin/workflow/triage.md`) — fast/standard/large:
 
 - **fast** (bugfix, typo, config tweak, wording-guidance สั้น, 1-2 ไฟล์ modify ของเดิม ไม่ cross-cutting): **fast-track** — ข้าม `business.md`, proposal/design สั้น, **ไม่ panel ไม่ dry-run**, 1 task; ทำตาม [fast-track skip-list](../triage.md#fast-track-skip-list) (canonical ใน `triage.md` — ไม่ลอก rubric มาที่นี่). **คง correctness floor:** spec/acceptance ขั้นต่ำของ task ยังต้องครบ
 - **standard** (feature ปกติ, modify หลายไฟล์/หลาย component, มี logic ใหม่): flow เต็ม — ครบทุก artifact, แตก vertical slice หลาย task + sub-task, dependency ชัด, panel/dry-run ตามเหมาะ

package/src/AGENTS.md

@@ -46,3 +46,9 @@ Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶
 ทำตาม `.warnyin/workflow/stages/discovery.md` — เริ่มอ่าน `docs/project.md`, ตี scope กว้าง→แคบ,
 ถามทีละข้อพร้อมเสนอคำตอบที่แนะนำ, คำถามที่ตอบได้ด้วยโค้ดให้ไปอ่านโค้ดเอง,
 เขียน output ลง `docs/stages/<slug>/discovery.md` และ `research.md`
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)
+
+> หมายเหตุ: global root doc ของ Codex/Antigravity ไม่รองรับรอบนี้ — convention นี้มีผลเฉพาะ per-project path

package/src/bin/cli.mjs

@@ -1,28 +1,50 @@
 #!/usr/bin/env node
 /**
  * warnyin-agents installer
- * ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน (cwd)
+ * ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน (cwd) หรือแบบ global (~/)
  *
- *   npx @warnyin/agents             ติดตั้ง (ข้ามไฟล์ที่มีอยู่แล้ว)
+ *   npx @warnyin/agents             ติดตั้งลงโปรเจกต์ (ข้ามไฟล์ที่มีอยู่แล้ว)
+ *   npx @warnyin/agents --global    ติดตั้งแบบ global (~/) ใช้ได้ทุกโปรเจกต์
+ *   npx @warnyin/agents --project   ติดตั้งลงโปรเจกต์ (บังคับ — ไม่ถาม)
  *   npx @warnyin/agents --update    อัปเดต playbook กลาง (เขียนทับเฉพาะไฟล์ core)
  *   npx @warnyin/agents --dry-run   แสดงว่าจะทำอะไร โดยไม่เขียนไฟล์จริง
  *   (ทางสำรองไม่ผ่าน npm: npx github:warnyin/warnyin-agents)
  */
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
 
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const target = process.cwd()
+const cwd = process.cwd()
 const args = new Set(process.argv.slice(2))
 const UPDATE = args.has('--update')
 const DRY = args.has('--dry-run')
 
+/**
+ * ★ pure function — เลือก mode จาก flag/TTY/answer (ไม่มี side-effect, export ให้ unit test)
+ * @param {{globalFlag?:boolean, projectFlag?:boolean, isTTY?:boolean, answer?:string}} o
+ * @returns {'project'|'global'}
+ */
+export function resolveMode({ globalFlag, projectFlag, isTTY, answer } = {}) {
+  if (globalFlag && projectFlag) {
+    throw new Error('--global กับ --project ใช้พร้อมกันไม่ได้ (เลือกอย่างใดอย่างหนึ่ง)')
+  }
+  if (globalFlag) return 'global'
+  if (projectFlag) return 'project'
+  if (!isTTY) return 'project' // CI-safe default — npx/pipe ไม่ค้างรอ input
+  const a = (answer ?? '').trim().toLowerCase()
+  return a === '2' || a === 'global' ? 'global' : 'project'
+}
+
 if (args.has('--help') || args.has('-h')) {
-  console.log(`warnyin-agents — ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน
+  console.log(`warnyin-agents — ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน หรือแบบ global
 
 ใช้งาน:
-  npx @warnyin/agents             ติดตั้ง (ข้ามไฟล์ที่มีอยู่แล้ว ไม่เขียนทับ)
+  npx @warnyin/agents             ติดตั้งลงโปรเจกต์ (ถ้า TTY จะถามก่อน; ข้ามไฟล์ที่มีอยู่แล้ว)
+  npx @warnyin/agents --global    ติดตั้งแบบ global ลง ~/ (~/.warnyin + ~/.claude) ใช้ได้ทุกโปรเจกต์
+  npx @warnyin/agents --project   ติดตั้งลงโปรเจกต์ (บังคับ ไม่ถาม)
   npx @warnyin/agents --update    อัปเดต playbook กลางเป็นเวอร์ชันล่าสุด
                                   (เขียนทับเฉพาะ .warnyin/workflow/, .claude/commands/warnyin/,
                                    template .warnyin/template/stages/[topic] — ไม่แตะ docs/ และงานจริง)
@@ -33,15 +55,15 @@ if (args.has('--help') || args.has('-h')) {
 }
 
 // guard กัน self-install — เก็บไว้แบบ defensive (zero-cost)
-// หลังย้าย source เข้า src/ → pkgRoot = src/ (sibling ของ bin/) จึงแทบไม่มีทาง === target (repo root / temp sandbox)
+// หลังย้าย source เข้า src/ → pkgRoot = src/ (sibling ของ bin/) จึงแทบไม่มีทาง === cwd (repo root / temp sandbox)
 // → guard นี้เป็น no-op โดยตั้งใจในเคสปกติ/sandbox; ยังคงดักได้เฉพาะ edge case ที่ install ลงโฟลเดอร์ที่เป็น src/ เอง
-if (path.resolve(pkgRoot) === path.resolve(target)) {
+if (path.resolve(pkgRoot) === path.resolve(cwd)) {
   console.error('✖ กำลังรันอยู่ใน repo ของ warnyin-agents เอง — ให้ cd ไปที่โปรเจกต์ปลายทางก่อน')
   process.exit(1)
 }
 
 // โครงเก่า (≤0.2.x): workflow/ + warnyin-stages/ ที่ root — เตือนให้ย้ายเอง ไม่แตะงานจริงของ user
-const legacyV2 = ['workflow', 'warnyin-stages'].filter((d) => fs.existsSync(path.join(target, d)))
+const legacyV2 = ['workflow', 'warnyin-stages'].filter((d) => fs.existsSync(path.join(cwd, d)))
 if (legacyV2.length) {
   console.warn(`⚠ พบโครงเลย์เอาต์เก่า (≤0.2.x): ${legacyV2.join(', ')}
 เวอร์ชันนี้ย้าย core ไปใต้ .warnyin/ และงานจริงไป docs/stages/ — แนะนำย้ายด้วยตัวเองก่อน:
@@ -52,7 +74,7 @@ if (legacyV2.length) {
 
 // โครงเก่า (0.3–0.5.x): ทุกอย่างอยู่ใต้ warnyin/ ที่ root — เวอร์ชันนี้แยกเป็น .warnyin/ (core) + docs/stages (งานจริง)
 const legacyV5 = ['workflow', 'template', 'installer', 'stages'].filter((d) =>
-  fs.existsSync(path.join(target, 'warnyin', d)),
+  fs.existsSync(path.join(cwd, 'warnyin', d)),
 )
 if (legacyV5.length) {
   console.warn(`⚠ พบโครงเลย์เอาต์เก่า (0.3–0.5.x): warnyin/{${legacyV5.join(', ')}}
@@ -79,6 +101,9 @@ const SCAFFOLD_FILES = [
 
 const stats = { created: 0, updated: 0, skipped: 0 }
 
+// target = ปลายทางที่จะเขียนไฟล์ — ตั้งหลัง resolve mode (project=cwd | global=homedir)
+let target = cwd
+
 function copyTree(relDir, { overwrite }) {
   const srcDir = path.join(pkgRoot, relDir)
   if (!fs.existsSync(srcDir)) return
@@ -173,21 +198,113 @@ function installRootDoc(name, srcPath) {
   console.log(`  ± ${name} (ต่อท้าย section Warnyin Standard Workflow)`)
 }
 
-console.log(`Warnyin Standard Workflow → ${target}${DRY ? '  (dry-run)' : ''}\n`)
+const GLOBAL_NOTE_MARKER = '<!-- warnyin:global-note -->'
 
-for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
-ensureScaffold()
-seedDocs()
-installRootDoc('CLAUDE.md', path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.md'))
-installRootDoc('AGENTS.md', path.join(pkgRoot, 'AGENTS.md'))
+/**
+ * เขียน resolution note ลง ~/.claude/CLAUDE.md แบบ note-only append-with-marker (global mode)
+ * — ห้ามเขียนทับทั้งไฟล์ (personal global memory ของ user); append เฉพาะถ้ายังไม่มี marker (idempotent)
+ * — defensive skip ถ้า template ไม่มี (worktree T1 เดี่ยวก่อน merge T2) — pattern เดียวกับ copyTree/seedDocs
+ */
+function installGlobalNote() {
+  const src = path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.global.md')
+  const destRel = path.join('.claude', 'CLAUDE.md')
+  const dest = path.join(target, destRel)
+  if (!fs.existsSync(src)) {
+    console.log(`  · ข้าม ${destRel} (ยังไม่มี template CLAUDE.global.md)`)
+    return
+  }
+  const note = fs.readFileSync(src, 'utf8')
+  if (!fs.existsSync(dest)) {
+    if (!DRY) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true })
+      fs.writeFileSync(dest, note)
+    }
+    stats.created++
+    console.log(`  + ${destRel}`)
+    return
+  }
+  const existing = fs.readFileSync(dest, 'utf8')
+  if (existing.includes(GLOBAL_NOTE_MARKER)) {
+    stats.skipped++
+    return
+  }
+  const section = (existing.endsWith('\n') ? '\n' : '\n\n') + note
+  if (!DRY) fs.appendFileSync(dest, section)
+  stats.updated++
+  console.log(`  ± ${destRel} (ต่อท้าย warnyin global note)`)
+}
+
+/** เลือก mode + ติดตั้งตาม mode (target=cwd|homedir). ห่อ async เฉพาะ path TTY (readline) */
+async function main() {
+  const globalFlag = args.has('--global')
+  const projectFlag = args.has('--project')
+  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+  let mode
+  try {
+    if (!globalFlag && !projectFlag && isTTY) {
+      // ถาม เฉพาะ path TTY — non-TTY/flag ไม่แตะ readline (ไม่ค้าง/ไม่ช้าลง)
+      const rl = createInterface({ input: process.stdin, output: process.stdout })
+      let answer
+      try {
+        answer = await rl.question('ติดตั้งแบบไหน? [1] โปรเจกต์นี้ (default) [2] global (~/) : ')
+      } finally {
+        rl.close()
+      }
+      mode = resolveMode({ globalFlag, projectFlag, isTTY, answer })
+    } else {
+      mode = resolveMode({ globalFlag, projectFlag, isTTY })
+    }
+  } catch (e) {
+    console.error(`✖ ${e.message}`)
+    process.exit(1)
+  }
+
+  if (mode === 'global') {
+    const home = os.homedir()
+    // homedir guard — falsy หรือ filesystem root (CI/container ไม่มี passwd) → error แทนเขียนลง root
+    if (!home || path.resolve(home) === path.parse(path.resolve(home)).root) {
+      console.error('✖ หา home directory ไม่ได้ (หรือเป็น filesystem root) — ใช้ --project แทน')
+      process.exit(1)
+    }
+    target = home
+    console.log(`Warnyin Standard Workflow → global ${target}${DRY ? '  (dry-run)' : ''}`)
+    console.log(`  จะเขียนนอกโปรเจกต์ที่: ${path.join(target, '.warnyin')}, ${path.join(target, '.claude', 'commands', 'warnyin')}, ${path.join(target, '.claude', 'CLAUDE.md')}\n`)
+    // first-install overwrite:false (skip ของเดิมใน ~/.claude/{agents,skills}) — ทับเฉพาะ --global --update
+    for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
+    // ข้าม scaffold/seedDocs (ยกให้ /warnyin:init) + ข้าม AGENTS.md global (DQ3 limitation)
+    installGlobalNote()
+  } else {
+    target = cwd
+    console.log(`Warnyin Standard Workflow → ${target}${DRY ? '  (dry-run)' : ''}\n`)
+    for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
+    ensureScaffold()
+    seedDocs()
+    installRootDoc('CLAUDE.md', path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.md'))
+    installRootDoc('AGENTS.md', path.join(pkgRoot, 'AGENTS.md'))
+  }
+
+  console.log(`\nสรุป: สร้างใหม่ ${stats.created} · อัปเดต ${stats.updated} · ข้าม (มีอยู่แล้ว) ${stats.skipped}`)
 
-console.log(`\nสรุป: สร้างใหม่ ${stats.created} · อัปเดต ${stats.updated} · ข้าม (มีอยู่แล้ว) ${stats.skipped}`)
+  if (!UPDATE) {
+    if (mode === 'global') {
+      console.log(`
+ติดตั้ง global แล้ว — /warnyin:* ใช้ได้ทุกโปรเจกต์ (จาก ~/.claude/commands/)
+  เปิดโปรเจกต์ใด ๆ ใน Claude Code → รัน  /warnyin:init  เพื่อสร้าง workspace (docs/) ของโปรเจกต์นั้น
 
-if (!UPDATE) {
-  console.log(`
+อัปเดต playbook ภายหลัง:  npx @warnyin/agents --global --update`)
+    } else {
+      console.log(`
 ขั้นถัดไป:
   1. เปิด Claude Code ในโปรเจกต์นี้ แล้วรัน  /warnyin:init  — ให้ agent วิเคราะห์โปรเจกต์ + เติม docs/
   2. เริ่มงานแรก:  /warnyin:discovery <topic>  หรือ  /warnyin:design <slug> <change>
 
 อัปเดต playbook ภายหลัง:  npx @warnyin/agents --update`)
+    }
+  }
+}
+
+// main-guard: รันเฉพาะตอน execute ตรง ๆ (ไม่ trigger ตอน import เพื่อ unit-test resolveMode)
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main()
 }