openmoneta-dev-kit 1.9.0

package/src/commands/init.js

@@ -0,0 +1,43 @@
+const { execSync } = require("node:child_process")
+const path = require("node:path")
+const { getPkgRoot, OPENCODE_DIR } = require("../lib/paths")
+
+async function run(args) {
+  let projectDir = process.cwd()
+  let isOpenCode = false
+  const remaining = []
+
+  for (const arg of args) {
+    if (arg === "--opencode") {
+      isOpenCode = true
+    } else if (arg.startsWith("-")) {
+      remaining.push(arg)
+    } else {
+      projectDir = arg
+    }
+  }
+
+  console.log(`\n  📁 Khởi tạo OpenMoneta Dev Kit cho project`)
+  console.log(`  Path: ${projectDir}`)
+
+  const pkgRoot = getPkgRoot()
+  const initScript = path.join(pkgRoot, "scripts", "init-project.sh")
+
+  // If opencode, use opencode install path
+  const env = { ...process.env }
+  if (isOpenCode) {
+    env.OPENMONETA_HOME = OPENCODE_DIR
+    console.log(`  Mode: OpenCode`)
+  }
+
+  try {
+    const cmd = `bash "${initScript}" "${projectDir}" ${remaining.join(" ")}`
+    console.log(`  Running: ${cmd}`)
+    execSync(cmd, { stdio: "inherit", env })
+  } catch (err) {
+    console.error(`\n  ❌ Init thất bại: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+module.exports = { run }

package/src/commands/install.js

@@ -0,0 +1,50 @@
+const { execSync } = require("node:child_process")
+const path = require("node:path")
+const { getPkgRoot, CURSOR_DIR, OPENCODE_DIR, isInstalled, REPO_DIR } = require("../lib/paths")
+const { getLocalVersion } = require("../lib/version")
+
+async function run(args) {
+  const isOpenCode = args.includes("--opencode")
+  const autoYes = args.includes("--yes") || args.includes("-y")
+  const target = isOpenCode ? "opencode" : "cursor"
+
+  const v = getLocalVersion() || "unknown"
+  const targetDir = isOpenCode ? OPENCODE_DIR : CURSOR_DIR
+  const targetLabel = isOpenCode ? "OpenCode" : "Cursor"
+
+  console.log(`\n  🔧 Cài OpenMoneta Dev Kit v${v} cho ${targetLabel}`)
+  console.log(`  Target: ${targetDir}`)
+
+  if (isInstalled(target) && !autoYes) {
+    const readline = require("node:readline")
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    const answer = await new Promise((resolve) => {
+      rl.question(`\n  ${targetLabel} đã được cài. Ghi đè? [y/N] `, resolve)
+    })
+    rl.close()
+    if (answer.toLowerCase() !== "y") {
+      console.log("  Hủy.")
+      return
+    }
+  }
+
+  const pkgRoot = getPkgRoot()
+
+  if (isOpenCode) {
+    console.log(`\n  Not yet implemented: use bash install-opencode.sh for now.`)
+    console.log(`    bash ${path.join(pkgRoot, "install-opencode.sh")}${autoYes ? " --yes" : ""}`)
+    return
+  }
+
+  // Call install.sh from package root
+  try {
+    const cmd = `bash "${path.join(pkgRoot, "install.sh")}"${autoYes ? " --yes" : ""}`
+    console.log(`\n  Running: ${cmd}`)
+    execSync(cmd, { stdio: "inherit", cwd: pkgRoot })
+  } catch (err) {
+    console.error(`\n  ❌ Cài đặt thất bại: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+module.exports = { run }

package/src/commands/uninstall.js

@@ -0,0 +1,74 @@
+const { unlinkSync, rmdirSync, existsSync, readdirSync, lstatSync } = require("node:fs")
+const path = require("node:path")
+const { execSync } = require("node:child_process")
+const { CURSOR_DIR, OPENCODE_DIR, isInstalled, getPkgRoot } = require("../lib/paths")
+
+function rmDir(dir) {
+  if (!existsSync(dir)) return
+  for (const entry of readdirSync(dir)) {
+    const p = path.join(dir, entry)
+    if (lstatSync(p).isDirectory()) {
+      rmDir(p)
+    } else {
+      unlinkSync(p)
+    }
+  }
+  rmdirSync(dir)
+}
+
+function rmFile(p) {
+  if (existsSync(p)) unlinkSync(p)
+}
+
+async function run(args) {
+  const purge = args.includes("--purge")
+  const autoYes = args.includes("--yes") || args.includes("-y")
+
+  if (!autoYes) {
+    const readline = require("node:readline")
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    const answer = await new Promise((resolve) => {
+      rl.question(`\n  ⚠ Gỡ cài đặt OpenMoneta Dev Kit? [y/N] `, resolve)
+    })
+    rl.close()
+    if (answer.toLowerCase() !== "y") {
+      console.log("  Hủy.")
+      return
+    }
+  }
+
+  console.log(`\n  🗑 Uninstalling OpenMoneta Dev Kit...`)
+
+  // Try calling uninstall.sh first (handles backup restore)
+  const pkgRoot = getPkgRoot()
+  const uninstallScript = path.join(pkgRoot, "uninstall.sh")
+  if (existsSync(uninstallScript)) {
+    try {
+      const flags = [autoYes ? "--yes" : "", purge ? "--purge" : ""].filter(Boolean).join(" ")
+      execSync(`bash "${uninstallScript}" ${flags}`, { stdio: "inherit" })
+      return
+    } catch {
+      console.log(`  Manual uninstall...`)
+    }
+  }
+
+  // Manual removal
+  for (const dir of [CURSOR_DIR, OPENCODE_DIR]) {
+    if (!existsSync(dir)) continue
+    for (const item of ["templates", "skills", "agents", "hooks", "scripts"]) {
+      const p = path.join(dir, item)
+      rmDir(p)
+    }
+    rmFile(path.join(dir, "hooks.json"))
+    rmFile(path.join(dir, ".openmoneta-version"))
+    rmFile(path.join(dir, ".openmoneta-repo"))
+    rmFile(path.join(dir, ".openmoneta-installed-at"))
+    rmFile(path.join(dir, ".openmoneta-update-check"))
+    rmFile(path.join(dir, "AGENTS.md"))
+  }
+
+  console.log(`\n  ✅ Đã gỡ cài đặt.`)
+  console.log(`     Restart Cursor/OpenCode để hoàn tất.`)
+}
+
+module.exports = { run }

package/src/commands/update.js

@@ -0,0 +1,81 @@
+const { execSync } = require("node:child_process")
+const path = require("node:path")
+const { getPkgRoot, isInstalled } = require("../lib/paths")
+const { getLocalVersion, getLatestVersion } = require("../lib/version")
+
+async function run(args) {
+  const checkOnly = args.includes("--check")
+  const autoYes = args.includes("--yes") || args.includes("-y")
+  const skipProjects = args.includes("--skip-projects")
+  const force = args.includes("--force")
+
+  const local = getLocalVersion()
+  const latest = getLatestVersion()
+
+  if (checkOnly) {
+    console.log(`\n  OpenMoneta Dev Kit`)
+    console.log(`  Local : v${local || "unknown"}`)
+    console.log(`  Latest: v${latest || "không xác định"}`)
+    if (latest && local && local !== latest) {
+      console.log(`\n  🔔 Cập nhật có sẵn: v${local} → v${latest}`)
+      console.log(`     Chạy: openmoneta update`)
+    } else if (latest && local && local === latest) {
+      console.log(`\n  ✅ Đã ở phiên bản mới nhất.`)
+    }
+    return
+  }
+
+  if (!isInstalled("cursor") && !isInstalled("opencode")) {
+    console.log(`\n  ❌ Chưa cài OpenMoneta. Chạy: openmoneta install`)
+    process.exit(1)
+  }
+
+  if (local && latest && local === latest && autoYes && !force) {
+    console.log(`\n  ✅ Already at latest version (v${local}), skipping. Dùng --force để cài lại.`)
+    return
+  }
+
+  console.log(`\n  🔄 Updating OpenMoneta Dev Kit...`)
+
+  const pkgRoot = getPkgRoot()
+
+  if (isInstalled("cursor")) {
+    console.log(`\n  ▶ Cursor global...`)
+    try {
+      execSync(`bash "${path.join(pkgRoot, "install.sh")}" --yes`, { stdio: "inherit", cwd: pkgRoot })
+    } catch {
+      console.error(`  ⚠ Cursor update failed`)
+    }
+  }
+
+  if (isInstalled("opencode")) {
+    console.log(`\n  ▶ OpenCode global...`)
+    try {
+      execSync(`bash "${path.join(pkgRoot, "install-opencode.sh")}" --yes`, { stdio: "inherit", cwd: pkgRoot })
+    } catch {
+      console.error(`  ⚠ OpenCode update failed`)
+    }
+  }
+
+  console.log(`\n  ✅ Global update done.`)
+
+  if (!skipProjects) {
+    const initScript = path.join(pkgRoot, "scripts", "init-project.sh")
+    const cwd = process.cwd()
+    const docsIndex = path.join(cwd, "docs", "INDEX.md")
+
+    try {
+      require("node:fs").accessSync(docsIndex)
+      console.log(`\n  ▶ Syncing project: ${path.basename(cwd)}`)
+      execSync(`bash "${initScript}" "${cwd}"`, { stdio: "inherit" })
+      console.log(`\n  ✅ Project synced.`)
+    } catch {
+      console.log(`\n  ℹ Không phát hiện project OpenMoneta ở thư mục hiện tại.`)
+      console.log(`     Sync thủ công: openmoneta init`)
+    }
+  }
+
+  console.log(`\n  🎉 Hoàn tất. Restart Cursor/OpenCode để áp dụng.`)
+}
+
+module.exports = { run }

package/src/lib/paths.js

@@ -0,0 +1,46 @@
+const path = require("node:path")
+const fs = require("node:fs")
+
+let ROOT = ""
+
+function getPkgRoot() {
+  return ROOT
+}
+
+const HOME = process.env.HOME || process.env.USERPROFILE || ""
+const XDG_CONFIG = process.env.XDG_CONFIG_HOME || path.join(HOME, ".config")
+
+const CURSOR_DIR = path.join(HOME, ".cursor")
+const OPENCODE_DIR = path.join(XDG_CONFIG, "opencode")
+const REPO_DIR = path.join(HOME, "OpenMoneta-Dev-Kit") // legacy
+
+function versionFilePath(target) {
+  if (target === "opencode") return path.join(OPENCODE_DIR, ".openmoneta-version")
+  return path.join(CURSOR_DIR, ".openmoneta-version")
+}
+
+function installedVersion(target) {
+  try {
+    return fs.readFileSync(versionFilePath(target), "utf8").trim()
+  } catch {
+    return null
+  }
+}
+
+function isInstalled(target) {
+  return installedVersion(target) !== null
+}
+
+module.exports = {
+  setPkgRoot(r) {
+    ROOT = r
+  },
+  getPkgRoot,
+  HOME,
+  CURSOR_DIR,
+  OPENCODE_DIR,
+  REPO_DIR,
+  versionFilePath,
+  installedVersion,
+  isInstalled,
+}

package/src/lib/version.js

@@ -0,0 +1,45 @@
+const { execSync } = require("node:child_process")
+const path = require("node:path")
+const fs = require("node:fs")
+const { getPkgRoot } = require("./paths")
+
+const PKG_NAME = "openmoneta-dev-kit"
+
+function getLocalVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(getPkgRoot(), "package.json"), "utf8"))
+    return pkg.version || null
+  } catch {
+    return null
+  }
+}
+
+function getLatestVersion() {
+  try {
+    return execSync(`npm view ${PKG_NAME} version 2>/dev/null`, {
+      encoding: "utf8",
+      timeout: 8000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+function checkUpdate() {
+  const local = getLocalVersion()
+  const latest = getLatestVersion()
+  if (!local || !latest) return null
+  return {
+    local,
+    latest,
+    needsUpdate: local !== latest,
+  }
+}
+
+module.exports = {
+  PKG_NAME,
+  getLocalVersion,
+  getLatestVersion,
+  checkUpdate,
+}

package/templates/AGENTS.md.tpl

@@ -0,0 +1,106 @@
+# AGENTS.md — Quy trình chuẩn (OpenMoneta Dev Kit v1.7.0+)
+
+> File này được tạo từ `~/.cursor/templates/AGENTS.md.tpl`. Chạy `bash ~/.cursor/scripts/init-project.sh .` để re-sync (idempotent, giữ phần `<!-- BEGIN PROJECT OVERRIDE -->`).
+
+## Nguyên tắc vàng
+
+1. **Trả lời tiếng Việt.**
+2. **Tuân thủ quy trình 6 bước cho mọi yêu cầu** (Bước 3 adaptive, Bước 6 chỉ chạy khi user yêu cầu push).
+3. **Đọc `docs/INDEX.md` ĐẦU TIÊN** mỗi session — hook `enforce-docs-first` sẽ chặn `Read/Glob/Grep` source code nếu chưa đọc.
+4. **Hỏi clarify TRƯỚC khi plan/code** — task trivial có thể skip; nếu có plan thì PHẢI ghi lý do/câu hỏi trong "## Hiểu yêu cầu".
+5. **Surgical changes** — mỗi dòng đổi phải trace về 1 task trong plan. Không "improve" code adjacent.
+6. **Simplicity First (Karpathy)** — không abstraction / config / error-handling không yêu cầu.
+7. **Safe Push** — khi user yêu cầu push, PHẢI sync remote ngay trước push; KHÔNG `git push --force` lên shared branch.
+
+## Quy trình 6 bước (B6 conditional)
+
+### Bước 1 — Phân tích yêu cầu (TOKEN-AWARE, HOOK ENFORCED)
+
+> Skill: `requirement-analysis`. Hook `enforce-docs-first` chặn Read source code nếu chưa đọc `docs/INDEX.md`.
+
+1. Read `docs/INDEX.md` (Modules + Token Routing) → match keyword user → 1-3 module candidate.
+2. Read `plans/INDEX.md` (check overlap với plan active).
+3. Read `docs/modules/<candidate>/README.md` (CHỈ module liên quan, không scan toàn bộ).
+4. Read source code module candidate (giờ hook unlock).
+5. Tóm tắt yêu cầu + giả thuyết + edge case + rủi ro.
+6. **Đặt câu hỏi critical để làm rõ yêu cầu** (`AskQuestion`) HOẶC khai báo `Lý do skip clarify` cho task trivial (typo, bump version, đổi 1 hằng số). Mục đích: làm rõ yêu cầu người dùng, phân tích tất cả trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có. Số lượng câu hỏi tùy thuộc vào độ phức tạp của task.
+
+### Bước 2 — Thiết kế module
+
+> Skill: `module-architect`.
+
+- 1 module = 1 trách nhiệm (SRP), mô tả 1 câu KHÔNG có "và".
+- **Feature mới**: áp dụng "Khi nào TẠO module mới" — feature có concept business riêng → module mới (KHÔNG nhét vào `utils/` / `common/` / `shared/`).
+- **Dự án EXISTING**: chạy Bước 2.0–2.3 (auto-detect module từ `apps/`, `packages/`, `src/modules/`); module bị sửa mà chưa có docs → backfill `docs/modules/<slug>/README.md` (3 sections: Trách nhiệm + Public API + Dependencies).
+- Module mới → BẮT BUỘC thêm 3-5 keyword vào bảng "Token Routing" của `docs/INDEX.md`.
+
+### Bước 3 — Adaptive Planning Gate
+
+> Skill: `plan-writer`. Plan KHÔNG bắt buộc cho task nhỏ. Plan BẮT BUỘC cho task lớn/rủi ro.
+
+- Task nhỏ/rõ ràng → không cần plan, triển khai luôn nhưng vẫn giữ surgical changes.
+- Task lớn/rủi ro/mơ hồ → tạo `plans/YYYY-MM-DD-<slug>.md` với `Status: Draft`, trình user review, chỉ triển khai sau khi user approve và đổi `Status: In Progress`.
+- Khi đã có plan `In Progress`, hook `check-plan-exists` enforce file scope theo `## Files ảnh hưởng` / `## Files thay đổi`.
+- Khi plan còn `Draft`, hook chặn code edit để tránh Agent tự approve plan.
+- Plan đụng >2 module → BẮT BUỘC thêm subsection "Lý do cross-module".
+- Update `plans/INDEX.md` (thêm vào Active).
+
+### Bước 4 — Triển khai
+
+- Nếu có plan active: chỉ edit file có trong `## Files ảnh hưởng` / `## Files thay đổi`.
+- Nếu không có plan: chỉ sửa đúng phạm vi user yêu cầu; phát hiện task vượt small/risk threshold → dừng, tạo plan Draft và xin review.
+- Mỗi sub-task xong → tick `- [x]` checkbox.
+- Cần mở rộng scope → update plan TRƯỚC khi sửa file mới.
+
+### Bước 5 — Update doc + close plan
+
+> Skill: `module-architect` (đã merge `doc-maintainer`). Hook `verify-completion` Check 6 chặn nếu module README thiếu.
+
+- Sync `docs/modules/<slug>/README.md` (Public API + Dependencies) nếu API đổi.
+- Module mới → đảm bảo đã có trong bảng "Modules hiện có" + "Token Routing" của `docs/INDEX.md`.
+- Plan → `Status: Done` + tick mọi checkbox.
+- **AUTO-ARCHIVE**: `git mv plans/<file>.md plans/archive/<file>.md` + update `plans/INDEX.md`.
+
+### Bước 6 — Pre-push Sync + Safe Push (CONDITIONAL)
+
+> Skill: `safe-push`. Chỉ chạy khi user yêu cầu `push`, `commit + push`, `đẩy code`, `merge lên remote`.
+
+- Trước `git push`, chạy `git fetch origin <branch>` + so sánh local/remote.
+- Nếu remote có commit mới → `git pull --rebase origin <branch>`.
+- Nếu conflict code logic → hỏi user, KHÔNG tự chọn ours/theirs.
+- Sau rebase/conflict → chạy lại verify tối thiểu phù hợp repo.
+- Push bằng `git push` thường. Nếu rejected vì remote mới → lặp lại fetch/rebase tối đa 3 vòng.
+- KHÔNG dùng `git push --force` hoặc `git push -f` trên `main`, `master`, `develop`, `staging`, `production`.
+
+## Sub-agents có sẵn (delegate khi cần isolation)
+
+| Subagent | Khi nào |
+|---|---|
+| `requirement-analyst` | Yêu cầu mơ hồ/lớn, cần đọc nhiều file |
+| `security-auditor` | **ON-DEMAND** — user yêu cầu audit security, hoặc task chạm auth/payment/PII |
+| `qa-autonomous` | **ON-DEMAND** — user yêu cầu viết unit/integration test |
+| `ui-tester` | **ON-DEMAND** — user yêu cầu Playwright UI/E2E test |
+
+## Skills có sẵn
+
+**Core (luôn relevant)**: `requirement-analysis`, `module-architect`, `plan-writer`.
+
+**Core conditional**: `safe-push` (Bước 6 — chỉ khi user yêu cầu push).
+
+**On-demand (chỉ trigger khi user yêu cầu rõ)**: `security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop`.
+
+## Hooks enforce
+
+| Hook | Khi nào | Hậu quả |
+|---|---|---|
+| `enforce-docs-first` | preToolUse Read/Glob/Grep | BLOCK source code đọc nếu chưa Read `docs/INDEX.md` |
+| `check-plan-exists` | preToolUse Write/StrReplace/EditNotebook/Delete | ALLOW task thường không plan; BLOCK file nhạy cảm không plan, plan Draft, hoặc file ngoài scope plan |
+| `verify-completion` | stop | BLOCK kết thúc nếu Check 5/6/9 fail (plan Done + checkbox, module README, "Hiểu yêu cầu") |
+
+## Override cho dự án này
+
+<!-- Thêm rule riêng của dự án bên dưới. Phần này được giữ lại khi chạy init-project.sh lần nữa. -->
+
+<!-- BEGIN PROJECT OVERRIDE -->
+
+<!-- END PROJECT OVERRIDE -->

package/templates/docs-INDEX.md.tpl

@@ -0,0 +1,62 @@
+# Docs Index
+
+> **Đây là điểm vào duy nhất cho AI khi mở dự án.** Hook `enforce-docs-first` (~/.cursor/hooks/) sẽ chặn `Read/Glob/Grep` trên `apps/`, `packages/`, `src/`, ... cho đến khi AI đã Read file này. Tiết kiệm 70-90% token bằng cách dùng bảng "Token Routing" để đến thẳng module liên quan.
+
+## Cấu trúc tài liệu
+
+<!-- BEGIN PROJECT DOC STRUCTURE -->
+| Đường dẫn | Mục đích |
+|---|---|
+| `docs/modules/<name>/README.md` | Mục đích, public API, deps của từng module |
+<!-- END PROJECT DOC STRUCTURE -->
+
+## Modules hiện có
+
+<!-- BEGIN PROJECT MODULES -->
+| Module | Source path | Trách nhiệm (1 câu, không có "và") |
+|---|---|---|
+| (chưa có) | | |
+<!-- END PROJECT MODULES -->
+
+## Feature / Keyword → Module (Token Routing)
+
+> **MỤC ĐÍCH**: AI ở Bước 1 (requirement-analysis) dùng bảng này để map yêu cầu user → module liên quan, sau đó chỉ đọc README của module đó thay vì scan toàn bộ docs/.
+>
+> **MAINTAIN**: mỗi khi tạo/đổi tên module → update bảng này. Keyword là từ tiếng Việt + tiếng Anh user thường gõ. Mỗi module nên có 3-5 keyword.
+
+<!-- BEGIN PROJECT TOKEN ROUTING -->
+| Keyword (VN/EN) | Module liên quan | Ghi chú |
+|---|---|---|
+| login, đăng nhập, OAuth, Google login, JWT, session, authentication | (vd: `auth`) | |
+| user, người dùng, profile, avatar | (vd: `user`) | |
+| payment, thanh toán, billing, invoice, subscription | (vd: `billing`) | |
+| email, mail, notification, thông báo, push, SMS | (vd: `notifications`) | |
+| upload, file, ảnh, image, storage, S3 | (vd: `storage`) | |
+| search, tìm kiếm, filter, sort | (vd: `search`) | |
+| (thêm dòng cho mỗi domain concept của dự án) | | |
+<!-- END PROJECT TOKEN ROUTING -->
+
+## Cách thêm module mới
+
+1. Tạo `docs/modules/<module-name>/README.md` với 3 sections:
+   - **Trách nhiệm**: 1 câu không có "và".
+   - **Public API**: function/class export.
+   - **Dependencies**: internal + external.
+2. Update bảng "Modules hiện có" ở trên.
+3. **BẮT BUỘC**: thêm 3-5 keyword vào bảng "Token Routing" (cho cả VN + EN).
+4. Tạo source folder tương ứng (`src/modules/<name>/` hoặc `apps/<name>/` hoặc `packages/<name>/`).
+
+## Plans hiện có
+
+Xem `plans/INDEX.md`.
+
+## Quy ước
+
+- Tài liệu **tiếng Việt**.
+- Tách module theo **SRP** (Single Responsibility), không theo số dòng. Chi tiết: skill `module-architect`.
+- Hook `verify-completion` Check 6 sẽ chặn session nếu code đã sửa nhưng module README chưa có.
+
+## Ghi chú riêng của dự án
+
+<!-- BEGIN PROJECT DOCS NOTES -->
+<!-- END PROJECT DOCS NOTES -->

package/templates/env.test.tpl

@@ -0,0 +1,16 @@
+# .env.test - GITIGNORED, KHÔNG commit lên git
+# File này được sinh tự động bởi init-project.sh. Token rotate mỗi lần bootstrap.
+# Dùng cho test local với cơ chế Test Bypass Flag (xem skill auth-bypass-testing).
+
+# Bật chế độ bypass auth - CHỈ HOẠT ĐỘNG khi NODE_ENV != 'production'
+ENABLE_TEST_BYPASS=true
+
+# Token random 64-char để authenticate test request. Phải khớp với header X-Test-Bypass-Token.
+TEST_BYPASS_TOKEN=__GENERATED_TOKEN__
+
+# Test user IDs hardcoded (xem tests/fixtures/test-users.json)
+TEST_USER_ID_DEFAULT=00000000-0000-0000-0000-000000000001
+TEST_USER_ID_ADMIN=00000000-0000-0000-0000-000000000002
+
+# IP whitelist - chỉ accept bypass request từ các IP này
+TEST_BYPASS_ALLOWED_IPS=127.0.0.1,::1,localhost

package/templates/karpathy-reference.md

@@ -0,0 +1,49 @@
+# Karpathy Behavioral Guidelines — Reference
+
+> Ghi chú: file này là **reference attribution** cho 4 nguyên tắc behavioral guideline của Andrej Karpathy được tích hợp vào OpenMoneta Dev Kit từ v1.2.0. Giữ nguyên tên + text gốc tiếng Anh để attribution rõ. Phần Việt hóa + áp dụng cụ thể nằm trong các skill được map bên dưới.
+
+## Source
+
+- Original guidelines: Karpathy behavioral guidelines (Cursor rule format `.mdc`).
+- Tích hợp vào OpenMoneta Dev Kit: v1.2.0.
+- Approach: INLINE — bổ sung vào skill hiện tại thay vì tạo skill mới riêng (tránh trùng lặp, AI bắt buộc đọc khi áp dụng skill ở từng bước).
+
+## 4 nguyên tắc gốc (English)
+
+| # | Nguyên tắc | Tóm tắt |
+|---|---|---|
+| 1 | **Think Before Coding** | State assumptions explicitly. If multiple interpretations exist, present them. If simpler approach exists, push back. If unclear, stop and ask. |
+| 2 | **Simplicity First** | Minimum code that solves the problem. No speculative features/abstractions/configurability/error-handling. "Would a senior engineer say overcomplicated?" → simplify. |
+| 3 | **Surgical Changes** | Touch only what you must. Don't "improve" adjacent code. Match existing style. Mention dead code, don't delete. Clean up only YOUR own orphans. Every changed line traces to user request. |
+| 4 | **Goal-Driven Execution** | Define verifiable success criteria. Bug fix: write reproducing test → fail → fix → pass. Multi-step plan: each step has a verify check. Strong criteria let agent loop independently. |
+
+## Mapping nguyên tắc → skill OpenMoneta
+
+| Karpathy | Skill OpenMoneta áp dụng | Section trong skill |
+|---|---|---|
+| #1 Think Before Coding | [`requirement-analysis`](../skills/requirement-analysis/SKILL.md) | Step 5: "Đề xuất cách đơn giản hơn" |
+| #2 Simplicity First | [`module-architect`](../skills/module-architect/SKILL.md) | "Anti-overengineering checklist" |
+| #3 Surgical Changes | [`plan-writer`](../skills/plan-writer/SKILL.md) | "Surgical Changes — line-level" |
+| #4 Goal-Driven (TDD bug fix) | [`test-strategy`](../skills/test-strategy/SKILL.md) | "Bug fix workflow (TDD bắt buộc)" |
+| #4 Goal-Driven (verify per step) | [`plan-writer`](../skills/plan-writer/SKILL.md) | "Tasks (mỗi task PHẢI có verify check)" |
+
+## Nguyên tắc vàng cấp dự án
+
+2 nguyên tắc rút gọn được thêm vào [`AGENTS.md.tpl`](./AGENTS.md.tpl) (inject mỗi session qua `sessionStart` hook):
+
+- **Nguyên tắc vàng #6**: Surgical changes — mỗi dòng đổi phải trace về plan.
+- **Nguyên tắc vàng #7**: Đơn giản tối thiểu — không abstraction/config/error-handling không yêu cầu.
+
+## Tradeoff (theo Karpathy gốc)
+
+> "These guidelines bias toward caution over speed. For trivial tasks, use judgment."
+
+OpenMoneta áp dụng tương tự:
+- Trivial task (vd: rename biến, sửa typo) → AI dùng judgment, không cần đầy đủ checklist.
+- Task ảnh hưởng >1 file hoặc thêm logic mới → bắt buộc apply 4 nguyên tắc.
+
+## Caveat khi áp dụng cho team Việt
+
+- "Push back" được phrase lại là "đề xuất thay thế" để tránh nghĩa chống đối.
+- "No error handling for impossible scenarios" KHÔNG mâu thuẫn với input validation: validate input của user là **bắt buộc** (xem `security-checklist`); chỉ tránh handle case **không thể xảy ra** trong contract code (vd: enum đã đủ cases nhưng vẫn `default: throw`).
+- "Match existing style" áp dụng kể cả khi style cũ không tối ưu — refactor style là task riêng, không gộp vào task khác.

package/templates/plans-INDEX.md.tpl

@@ -0,0 +1,38 @@
+# Plans Index
+
+> AI cập nhật bảng này mỗi khi tạo/hoàn thành plan. Từ v1.7.0, task nhỏ có thể không cần plan; task lớn/rủi ro tạo plan `Draft`, user review, rồi mới `In Progress`. Plan Done được auto-archive sang `plans/archive/` để giảm noise khi AI scan plans/ folder.
+
+## Active (đang triển khai)
+
+<!-- BEGIN ACTIVE PLANS -->
+| Plan | Mục tiêu | Trạng thái | Ngày tạo |
+|---|---|---|---|
+| (chưa có) | | | |
+<!-- END ACTIVE PLANS -->
+
+## Extra / Legacy Plan Sections
+
+<!-- BEGIN PROJECT PLANS EXTRA -->
+<!-- END PROJECT PLANS EXTRA -->
+
+## Archived (đã Done, đã move sang plans/archive/)
+
+<!-- BEGIN ARCHIVED PLANS -->
+| Plan | Mục tiêu | Hoàn thành | Plan archive path |
+|---|---|---|---|
+| (chưa có) | | | `plans/archive/...` |
+<!-- END ARCHIVED PLANS -->
+
+## Quy ước
+
+- File plan: `plans/YYYY-MM-DD-<slug-kebab-case>.md`.
+- Slug: ngắn gọn, mô tả tính năng/fix chính (vd: `add-google-login`, `fix-cart-overflow`).
+- Status trong file: `Draft` (chờ user review) → `In Progress` (đã approve) → `Done`.
+- **Auto-archive**: ngay khi đổi Status → Done, chạy `git mv plans/<file>.md plans/archive/<file>.md` và update bảng Archived bên trên.
+- Plan template: 5 sections (Hiểu yêu cầu, Mục tiêu, Modules ảnh hưởng, Files ảnh hưởng, Tasks). Plan minimal chỉ dùng khi vẫn muốn audit cho task nhỏ.
+- Skill: `~/.cursor/skills/plan-writer/SKILL.md`.
+
+## Ghi chú riêng của dự án
+
+<!-- BEGIN PROJECT PLANS NOTES -->
+<!-- END PROJECT PLANS NOTES -->

package/templates/playwright.config.ts.tpl

@@ -0,0 +1,44 @@
+import { defineConfig, devices } from '@playwright/test';
+import * as dotenv from 'dotenv';
+import * as path from 'path';
+
+dotenv.config({ path: path.resolve(__dirname, '.env.test') });
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['list'],
+    ['html', { outputFolder: 'tests/playwright-report', open: 'never' }],
+  ],
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3000',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    extraHTTPHeaders: process.env.TEST_BYPASS_TOKEN
+      ? {
+          'X-Test-Bypass-Token': process.env.TEST_BYPASS_TOKEN,
+          'X-Test-User-Id': process.env.TEST_USER_ID_DEFAULT || '',
+        }
+      : {},
+  },
+  projects: [
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 13'], viewport: { width: 375, height: 812 } },
+    },
+    {
+      name: 'tablet',
+      use: { ...devices['iPad (gen 7)'], viewport: { width: 768, height: 1024 } },
+    },
+    {
+      name: 'desktop',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1440, height: 900 } },
+    },
+  ],
+  outputDir: 'tests/screenshots/_playwright-output',
+});