@fui-org/fui-cli 0.2.0 → 0.3.0

package/skills/fui-skill/references/module-data-patterns.md

@@ -0,0 +1,126 @@
+# module.json `data[]` — Khai báo state & value resolution (chuyên sâu)
+
+> File này sở hữu: **pattern khai báo `data[]`: ba loại phần tử, thứ tự state → named action → auto-startup**. Value resolution xem [controls-patterns.md](controls-patterns.md) §0; cú pháp key lồng nhau (dot/bracket/`#PARENT`) xem [controls-patterns.md](controls-patterns.md) §1; trao đổi cross-window xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+Cách FUI đọc `data[]`: xử lý **tuần tự từ trên xuống**, mỗi object gán/chạy dựa trên cách viết value. Ví dụ trong file này rút từ `ex/ex-v3-1SetData` + `ex-v3-2CauTruc` (module demo chính thức của FUI).
+
+> Quy tắc value resolution hình thức: [controls-patterns.md](controls-patterns.md) §0. Tổng quan 4 thành phần: [module-json-anatomy.md](module-json-anatomy.md). Engine nền tảng: [platform-architecture.md](platform-architecture.md) §5.
+
+---
+
+## 1. Ba loại phần tử trong `data[]`
+
+```json
+"data": [
+  { "keyword": "", "dsUser": [], "dlOpen": false },          // (a) khởi tạo state
+  { "getUser": { "API": "...", "IN": {...}, "OUT": "dsUser" } }, // (b) named action
+  { "API": "...", "OUT": "dsInit" },                          // (c) action tự chạy khi load
+  { "CALL": "getUser" }                                        // (c) auto-startup
+]
+```
+
+- (a) không có key action → tạo biến reactive trong `vueData`.
+- (b) key là **tên hàm** → định nghĩa action tái sử dụng (gọi bằng `CALL`).
+- (c) object là chính một action (`API`/`CALL`/`FUN`…) → **chạy ngay khi trang load**, theo thứ tự.
+
+---
+
+## 2. Value resolution — CÁCH VIẾT quyết định GIÁ TRỊ (điểm hay sai)
+
+Bảng quy tắc đầy đủ (`getVueData`: backtick / `{{ }}` / chuỗi có dấu cách / chuỗi không dấu cách →
+JS eval) nằm ở [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental)
+— file Tier A luôn được nạp sẵn, không chép lại ở đây.
+
+> **Hệ quả cho AI khi viết `data[]`:** muốn gán **chuỗi cố định không dấu cách** (id, url, mã) →
+> **bọc backtick** (`` "`winUser" ``) hoặc single-quote (`"'winUser'"`), nếu không FUI sẽ hiểu là
+> biến. Đây là lỗi phổ biến nhất khi viết `data`/`IN`.
+
+---
+
+## 3. Key là đường dẫn lồng nhau (deep set)
+
+Key bên trái cũng được phân giải (dot / bracket / index động / `#PARENT`) — bảng cú pháp đầy đủ nằm ở
+[controls-patterns.md §1](controls-patterns.md#1-khai-báo-và-gán-dữ-liệu-trong-data) *(Tier A, đã nạp sẵn)*,
+không chép lại ở đây.
+
+---
+
+## 4. Action tự chạy: inline `IN`/`OUT`/`API` khi load
+
+Object là action đứng riêng trong `data[]` → chạy khi load. Không cần đặt tên:
+
+```json
+{ "API": "https://tapi.example.vn/me/auth/ApplicationList", "OUT": "Mang" },
+{ "IN": { "ABC": "`gdsgdsg", "DEF": "val5", "CBV": 1233 }, "OUT": "DoiTuong" }
+```
+
+→ dùng để nạp dữ liệu ban đầu của trang (danh mục, dropdown, dữ liệu bảng).
+
+---
+
+## 5. Named action + CALLBACK (tái sử dụng)
+
+```json
+{
+  "cmdSETData": [
+    { "MESS": "Thông báo" },
+    { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }
+  ],
+  "apiChart": {
+    "API": "/ts/TS_Report_ForChart/{{ab}}",
+    "IN": { "sachID": "apiLoadFBUser", "modeY": 12345 },
+    "OUT": "DSDoiQuaTang",
+    "CALLBACK": { "AAA": "val2" }
+  }
+}
+```
+
+Gọi bằng `{ "CALL": "cmdSETData" }` từ `controls`, `watch`, hay action khác. `CALLBACK` chạy sau khi API xong (xem [ui-patterns.md](ui-patterns.md) §7).
+
+---
+
+## 6. `watch` với `v_old` — giá trị cũ
+
+Trong `watch`, `v_old.<field>` cho giá trị **trước khi đổi**:
+
+```json
+"watch": {
+  "val4": {
+    "API": "ts/auth/QuanHuyen_Select",
+    "IN": { "MaTinhTP": "tinhID" },
+    "OUT": "DS_QUAN_HUYEN",
+    "CALLBACK": { "BAC": "v_old.abcdeID" }
+  },
+  "taoID": { "dungthu": "v_old.taoID" }
+}
+```
+
+Chi tiết `v_old`, `deep-watch`: [watcher-patterns.md](watcher-patterns.md).
+
+---
+
+## 7. Trao đổi cross-window ngay trong `data[]`
+
+`data[]` có thể đọc/ghi cửa sổ khác bằng key/value `#PARENT.*` / `#WinID.*` — đặt **trước** các CALL fetch:
+
+```json
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1",   // đọc data cha
+    "#PARENT.abcdef": 1234567890,        // ghi xuống cha
+    "#Win1": { "CALL": "cmdTHONGBao" }   // gọi lệnh ở Win1
+  }
+]
+```
+
+Đầy đủ: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+---
+
+## 8. Checklist viết `data[]`
+
+1. Khởi tạo **mọi** biến state ở object đầu (kể cả `[]`, `false`, `null`) — để reactive hoạt động.
+2. Named action nhóm giữa; auto-startup (`CALL`/`API`) đặt **cuối**.
+3. Gán chuỗi cố định không dấu cách → **backtick**; đừng để FUI hiểu nhầm là biến.
+4. `#PARENT.*` / biến từ URL đặt trước các CALL fetch.
+5. Không nhồi logic phức tạp vào `data` — tách sang `script.js` (hàm) hoặc `EXE` dè xẻn.

package/skills/fui-skill/references/module-json-anatomy.md

@@ -0,0 +1,137 @@
+# module.json Anatomy — 4 thành phần: data · watch · controls · set
+
+> File này sở hữu: **4 thành phần `module.json` (data/watch/controls/set) — vai trò và cách chúng tương tác, checklist cấu trúc**. Cú pháp action/control chi tiết xem [controls-patterns.md](controls-patterns.md).
+
+`module.json` mô tả một trang FUI. Nó có đúng **4 khối cấp 1**. File này giải thích *vai trò, cách cấu hình, tác động* và *tương tác* giữa chúng, rồi trỏ tới file chuyên sâu cho từng loại pattern.
+
+> Cơ chế nền tảng (runtime đọc module.json thế nào): [platform-architecture.md](platform-architecture.md). Pattern UI thực tế (ưu tiên cao, đã tinh chỉnh qua thực chiến): [ui-patterns.md](ui-patterns.md).
+
+```json
+{
+  "data":     [ /* state + action */ ],
+  "watch":    { /* observer → action */ },
+  "controls": [ /* layout UI: container > rows > cols */ ],
+  "set":      { /* override config trang (tùy chọn) */ }
+}
+```
+
+Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch` → merge `set` vào config trang. Tất cả state sống trong `vueData`.
+
+---
+
+## 1. `data` — Mảng khởi tạo state + định nghĩa Action
+
+**Là gì:** một **mảng**. FUI xử lý tuần tự từ trên xuống khi trang load.
+
+**Ba loại phần tử trong `data[]`:**
+
+| Loại object | Nhận biết | Tác động |
+|---|---|---|
+| Khởi tạo state | Không có key action (`API`/`CALL`/`IF`...) | Tạo biến reactive trong `vueData` |
+| Named action | Key là tên hàm, value là object action | Định nghĩa action tái sử dụng (gọi qua `CALL`) |
+| Auto-startup | `{ "API": ... }` hoặc `{ "CALL": ... }` đứng riêng | **Tự chạy** ngay khi load |
+
+```json
+"data": [
+  { "dsUser": [], "sGroup": null, "dlUserInfo": false },
+  {
+    "getUser": { "API": "SM_Users_SelectByDepGroup", "IN": { "GroupID": "sGroup" }, "OUT": "dsUser" }
+  },
+  { "CALL": "getUser" }
+]
+```
+
+**Tác động:** mọi biến khai báo ở đây thành reactive state; action đặt tên ở đây gọi được từ `watch`, `controls`, hay action khác. Auto-startup ở cuối = dữ liệu ban đầu của trang.
+
+**Chi tiết:** khai báo `data[]` + value resolution (chuỗi/biến/backtick/`{{ }}`/deep key, action tự chạy, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; engine action → [controls-patterns.md](controls-patterns.md); tổ chức data thực tế → [ui-patterns.md](ui-patterns.md) §1–2.
+
+---
+
+## 2. `watch` — Observer: state đổi → chạy action
+
+**Là gì:** một **object** `{ "tênBiến": action }`. Khi biến đổi giá trị, action chạy.
+
+```json
+"watch": {
+  "sGroup":      { "CALL": "getUser" },
+  "sDepartment": { "CALL": "getUser" },
+  "sModuleID":   [ { "CALL": "getSysRight" }, { "CALL": "getFunctionRight" } ]
+}
+```
+
+**Tác động & mẫu dùng:**
+- **Cascading filter**: mỗi dropdown lọc có một watch → tự reload bảng khi đổi.
+- Nhiều action cho một biến → dùng **mảng**.
+- **`deep-watch`**: theo dõi thay đổi sâu bên trong object/array (runtime hỗ trợ key `deep-watch`).
+
+**Chi tiết:** [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
+
+---
+
+## 3. `controls` — Layout UI (bắt buộc grid container > rows > cols)
+
+**Là gì:** một **mảng** container. Runtime dựng: `container (v-container)` → `rows (v-layout)` → `cols` → mỗi phần tử là một **Control Object**.
+
+```json
+"controls": [
+  {
+    "prop": "fluid grid-list-md",
+    "rows": [
+      { "prop": "row", "cols": [ /* Control Objects */ ] }
+    ]
+  }
+]
+```
+
+**Control Object** — các key chính:
+
+| Key | Vai trò |
+|---|---|
+| `el` | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom) |
+| `attr` | Thuộc tính/directive (`class`, `style`, `v-model`, `v-on:click`) — **dùng `v-on:click`, KHÔNG `@click`** |
+| `w` | Bề rộng cột: `1–12` (grid) hoặc `>= 25` (px, **bắt buộc kèm `col: { "class": "shrink" }`**). Không dùng 13–24. Bắt buộc cho item trong `cols` |
+| `col` | Cấu hình cột grid bao ngoài (`class`, `style`, `v-if`) |
+| `innerHTML` | Nội dung: string (hỗ trợ `{{ }}`) hoặc mảng Control Object lồng nhau |
+
+**Tác động:** đây là toàn bộ giao diện trang. Quy tắc bắt buộc: luôn bắt đầu bằng grid wrapper; dùng `innerHTML` (mảng) để lồng, không dùng `children`; dialog đặt trong container `prop: "hidden-container"`.
+
+**Chi tiết:** cấu trúc & grid → [controls-patterns.md](controls-patterns.md) §6; **class/prop/style được dùng (đừng tự thêm style)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); chọn component → [component-quickref.md](component-quickref.md); pattern layout/table/dialog → [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [ui-dialog-patterns.md](ui-dialog-patterns.md), [ui-layout-patterns.md](ui-layout-patterns.md).
+
+---
+
+## 4. `set` — Override config cho riêng trang (tùy chọn)
+
+**Là gì:** một **object** override config cấp project cho trang này. Runtime trộn `project.json` rồi `set` (module thắng) — xem [platform-architecture.md](platform-architecture.md) §2.1.
+
+```json
+"set": {
+  "title": "Quản lý sinh viên",
+  "menu": false
+}
+```
+
+**Tác động:** chỉ khai báo field khác với project. Thường dùng: `title` (tiêu đề trang), `menu: false` (ẩn header — sub-window/landing), `menuLeft` (sidebar riêng), `apiDomain` (đổi backend trang đó). Trang bình thường **không cần `set`** (kế thừa hết project).
+
+**Chi tiết & danh mục thuộc tính đầy đủ:** [project-config.md](project-config.md).
+
+---
+
+## Tương tác giữa 4 thành phần
+
+```
+URL ?param  ──►  vueData[param]         (inject trước khi data chạy)
+data[]      ──►  tạo state + action, auto-startup fetch
+controls    ──►  bind hai chiều vào state (v-model), gọi action (:action / v-on)
+watch       ──►  state đổi → chạy action → cập nhật state khác → UI re-render
+set         ──►  quyết định khung trang (title/menu/apiDomain) bao quanh controls
+```
+
+Vòng lặp điển hình: user thao tác trên `controls` → đổi state → `watch` bắt → gọi `API` action trong `data` → `OUT` cập nhật state → `controls` render lại.
+
+## Checklist khi viết module.json
+
+1. `data[]`: state trước → named action → `{ "CALL": ... }` auto-startup cuối
+2. `watch`: mọi filter/dropdown đều có watch → reload
+3. `controls`: bắt đầu bằng grid wrapper; `w` cho mọi item; dialog trong `hidden-container`; `v-on:click` không `@click`
+4. `set`: chỉ khai báo khi trang khác project default
+5. Tham chiếu state bằng `vueData.` trong controls/attr; JSON hợp lệ (không trailing comma)

package/skills/fui-skill/references/module-structure.md

@@ -0,0 +1,260 @@
+# Module Structure (Canonical for Workspace and Chat)
+
+> File này sở hữu: **cây thư mục project/module, trách nhiệm từng file, `_moduleInfo.json`/`mTitle`, chế độ `HTMLOnly`, meta tag mặc định**. Quy tắc viết `uc-*.vue` xem [component-design.md](component-design.md); nội dung bên trong `module.json` xem [controls-patterns.md](controls-patterns.md). *(Tier A — luôn nạp cùng `skill_get`.)*
+
+Use this structure when creating, refactoring, or reviewing a FUI module.
+
+- In editor or extension contexts with workspace access, apply it as the real local folder structure.
+- In chat or agent-chat contexts, use it to virtualize the same module structure and organize the response, without assuming the files already exist on disk.
+
+## Canonical Local Structure
+
+The workspace is organized at two levels: **project** and **module**.
+
+### Project-level (root of a checked-out project)
+
+```text
+{projectId}/
+|-- _projectInfo.json             # Project metadata (ProjectID, ProjectName, Framework, etc.)
+|-- project.json                  # Full project config (data/watch/controls/set at project scope)
+|-- imports/                      # Project-scope import files
+|   `-- _imports.json             # Declared project-level JS/CSS imports
+|-- components/                   # Project-scope Vue components
+|   |-- _components.json          # Component registry
+|   `-- uc-*.vue                  # Project-level custom components
+|-- modules/                      # All modules in this project
+|   |-- _modules.json             # Module list metadata
+|   `-- {moduleId}/               # One folder per module (see module-level below)
+`-- skills/                       # FUI skill files (auto-copied on checkout)
+```
+
+### Module-level (inside `modules/{moduleId}/`)
+
+```text
+{moduleId}/
+|-- _moduleInfo.json              # Required: module metadata + mTitle (page title) + HTMLOnly
+|-- module.json                   # Required: data/watch/controls/set (unused when HTMLOnly=true)
+|-- script.js                     # Recommended: helper logic for FUN/EXE/chart/transform
+|-- style.css                     # Optional: module-wide CSS (published via module_publish_css)
+|-- header.html                   # Full <head> content: <link>, <style>, <script> tags
+|-- body.html                     # HTMLOnly=false: supplementary body HTML
+|                                 # HTMLOnly=true: entire page content (custom HTML/Vue app)
+|-- imports/                      # Module-scope import files
+|   `-- _imports.json             # Declared module-level JS/CSS imports
+`-- components/                   # Optional: custom Vue components
+    |-- _components.json          # Required when using custom components
+    `-- uc-*.vue                  # Custom components (prefix uc-)
+```
+
+## Chat-Safe Usage
+
+When working without local workspace access:
+
+1. Present this tree as the canonical module layout, not as a claimed filesystem state.
+2. Return file contents in separate code blocks or clearly labeled sections.
+3. Ask the user to paste `_moduleInfo.json`, `module.json`, `script.js`, or component files when a review or patch depends on existing code.
+4. Scope recommendations to the files actually provided instead of inventing unseen surrounding files.
+
+## Required vs Optional
+
+1. Required (module-level):
+- `_moduleInfo.json`
+- `module.json`
+
+2. Recommended:
+- `script.js`
+- `imports/_imports.json`
+
+3. Optional by use-case:
+- `header.html`
+- `body.html`
+- `style.css`
+- `components/` (with `_components.json` and `uc-*.vue`)
+
+## File Responsibilities
+
+### module.json (core)
+- Keep all runtime config in `data`, `watch`, `controls`, `set`.
+- Keep `controls` under FUI grid wrapper (`container > rows > cols`).
+- Keep business actions in `data` and trigger with `CALL`.
+- **When `HTMLOnly=true`: leave this file empty (`data:[], watch:{}, controls:[], set:{}`). The FUI runtime does not use it.**
+- **JSON content patterns** (data[], watch, controls, actions, dialogs, navigation): see [`examples/module-patterns.json`](../examples/module-patterns.json)
+- **f-table props and header types**: see [`examples/f-table-patterns.json`](../examples/f-table-patterns.json)
+
+### script.js (helper logic)
+- Move complex transforms, chart builders, debounce helpers, parsing logic here.
+- Expose functions for `FUN` actions or template helpers.
+- Avoid large inline `EXE` blocks in `module.json` when reusable function is possible.
+
+### style.css (module-wide CSS)
+- CSS not tied to a single component — shared/global rules for the module.
+- Published via `module_publish_css` (mirrors `script.js`/`module_publish_script`); does not auto-clear on `module_publish_html` if left empty.
+- Component-local CSS belongs in the component's own `<style scoped>` (see [component-design.md](component-design.md)), not here.
+
+### _moduleInfo.json (metadata)
+- Keep `ProjectID`, `ModuleID`, `ModuleName`, `Framework` accurate.
+- Contains `mTitle` (page title). To update the module's page title, edit the `mTitle` field in `_moduleInfo.json`. This value is sent to the server as `title` when publishing via `module_publish_html`.
+- Contains `HTMLOnly` (boolean). **Read this first before deciding how to structure the module.**
+
+### header.html (head content)
+- Contains everything that goes **inside** the `<head>` tag — do NOT include the `<head>` wrapper itself.
+- Can contain: `<link>` CSS imports, `<style>` blocks, `<script>` imports, `<meta>` tags.
+- Do NOT put a `<title>` tag here — page title is managed via `mTitle` in `_moduleInfo.json`.
+- **Default meta tags — already present on every FUI page, do NOT repeat them in header.html:**
+  ```html
+  <meta charset="UTF-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"/>
+  ```
+  These defaults affect UI design decisions: `user-scalable=no, maximum-scale=1` means users **cannot pinch-zoom** — fonts/buttons must be readable and tappable at natural size on mobile; `width=device-width, initial-scale=1` makes Vuetify breakpoints behave per real device CSS pixels; `viewport-fit=cover` lets the page extend into the iOS notch/home-indicator area — fullscreen/`HTMLOnly` layouts touching top/bottom edges need `env(safe-area-inset-*)` padding.
+- For `HTMLOnly=false`: typically only CSS (`<link>` and `<style>`). Framework and project-level scripts are injected automatically by the server.
+- For `HTMLOnly=true`: **you must bring your own runtime** — see [HTMLOnly=true: KHÔNG có thư viện nào được nhúng sẵn](#htmlonlytrue-không-có-thư-viện-nào-được-nhúng-sẵn) below before writing a single tag.
+
+### body.html (body content)
+- Contains everything that goes **inside** the `<body>` tag — do NOT include the `<body>` wrapper itself.
+- **When `HTMLOnly=false`**: supplementary HTML rendered alongside the FUI Vue runtime. Usually empty or minimal.
+- **When `HTMLOnly=true`**: the **entire page content**. Can be plain HTML or a fully custom Vue app (own `<div id="app">`, own `<v-app>`, etc.). The FUI default Vue mount point is hidden in this mode.
+- Both `header.html` and `body.html` store only the **inner content** (no wrapper tags). The server strips wrappers automatically on save, and the publish tool does the same preprocessing.
+
+### imports/_imports.json (module imports)
+- Declares module-scope JS/CSS import files.
+- Each entry: `{ name, type, contentType, fileID, scope, sort }`.
+- `sort` — thứ tự load. **Khi thêm import mới: đặt `sort` từ 40 trở lên** (40, 50, 60...). Giá trị nhỏ (1–39) dành cho import hệ thống/framework được load trước — không dùng để tránh xung đột.
+- Only module-scope imports are stored here (project-scope imports are at `{projectId}/imports/_imports.json`).
+
+### components/_components.json
+- Register `uc-*` components.
+- Follow upsert rule:
+  - Before publish: may only have `comName`.
+  - After publish/sync: `comID` is server-managed.
+- Do not handcraft random `comID`.
+
+### components/uc-*.vue
+- Use `uc-` prefix for custom components.
+- Keep component-specific UI complexity here instead of bloating `module.json`.
+- Prefer reusable component contracts: props for input, emits for output, slots for extensibility.
+- Avoid baking page-specific API calls or route logic into the component unless that coupling is intentional and unavoidable.
+- `<style scoped>` blocks are allowed, but `scoped` has no real scoping effect — every selector must be manually prefixed with a unique class matching the component name. See [component-design.md](component-design.md) for the full rule and example.
+- Never use backtick template strings inside the component `<template>`.
+
+### _projectInfo.json (project metadata)
+- Saved at project root on checkout (`{projectId}/_projectInfo.json`).
+- Contains `ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `fetchedAt`.
+- Read-only for module editing — do not modify.
+
+### project.json (project config)
+- Contains a single `data` object — project-level defaults for all modules: `apiDomain`, `login`, `userInfo`, `menu`, `menuLeft`, `menuStyle`, `menuComponent`, `domainSetting`, etc.
+- **Relationship with `module.json` `set`**: runtime merges `project.json data` + `module.json set`, with module values taking priority. A module only needs to declare fields that differ from the project default.
+- See [project-config.md](project-config.md) for full field reference, menu item structure, and `right` permission rules.
+
+## Naming and Prefix Rules
+
+1. Module folder name:
+- Use the same module ID naming used by project conventions.
+
+2. Custom component file:
+- Use `uc-*.vue` kebab-case.
+
+3. Component usage in `module.json`:
+- Use `el: "uc-..."` for custom components.
+- Keep prop binding in `attr` with kebab-case prop names.
+
+## HTMLOnly Mode
+
+`HTMLOnly` is a boolean flag in `_moduleInfo.json`. **Always check this first** before editing a module.
+
+### HTMLOnly=false (default — FUI Vue module)
+
+- `module.json` is the core: FUI runtime reads `data`, `watch`, `controls`, `set` and bootstraps a Vue app.
+- `body.html` is supplementary HTML rendered in the body alongside the Vue controls (often empty).
+- `header.html` typically contains CSS only (`<link>`, `<style>`). Framework and project-level scripts are auto-injected by the server.
+- Vue components (`uc-*.vue`) are fully supported.
+- `script.js` exposes helper functions used by `FUN`/`EXE` actions.
+
+### HTMLOnly=true (custom HTML/Vue page)
+
+- `module.json` is **ignored** at runtime — keep it empty (`data:[], watch:{}, controls:[], set:{}`).
+- `body.html` is the **entire page content**. The developer has full control — can write plain HTML or a completely custom Vue app (own `<div id="app">`, own `<v-app>`, own Vue instance).
+- Do NOT attempt to use FUI's `controls`/`data`/`watch` JSON system — it has no effect.
+- Use this mode for: standalone tools, custom editors, pages that need their own runtime or layout that doesn't fit the FUI grid system.
+- **Full-height layout**: nếu trang có `menu` hiển thị (không phải `set.menu: false`), thanh menu chiếm 48px cố định — mọi CSS `height: 100vh` hay `calc(100vh - Npx)` trên container gốc phải cộng thêm 48px vào phần trừ. Xem [project-config.md](project-config.md) §menu.
+
+#### HTMLOnly=true: KHÔNG có thư viện nào được nhúng sẵn
+
+Đây là điều hay bị hiểu sai nhất về chế độ này, và hiểu sai thì **không có lỗi nào nổi lên lúc
+viết** — chỉ là trang trắng sau khi deploy.
+
+Với `HTMLOnly=true`, server chỉ phát ra **ba** thứ:
+
+1. import **của chính module này** (`{moduleId}/imports/_imports.json`),
+2. StyleCSS **cấp module** (`style.css` + `<style>` của `uc-*.vue` cấp module),
+3. bundle `moduledata` (`$moduleUI` + `script.js` + component cấp module).
+
+Tất cả những thứ sau **KHÔNG** được nhúng — kể cả khi project đang khai chúng:
+
+| Không có | Hệ quả nếu bạn cứ giả định là có |
+|---|---|
+| Framework V2/V3 — `vue.global.min.js`, `vuetify*.js/css`, `fastproject*.js`, `component*.js`, `defaultfunction*.js` | `Vue is not defined`, `<v-btn>` không render, `f-*`/`t-*` không tồn tại |
+| jQuery, lodash (`_`), `moment`/`dayjs`, `numeral`, `jquery-confirm` | `$ is not defined`, `_ is not defined` |
+| Roboto, Material Design Icons (`mdi-*`) | chữ sai font, icon thành ô vuông trống |
+| `projectdata` bundle — `$projectData`, `$projectGroupSetting`, component cấp **project** | `apiDomain`/`menu`/`login` đều undefined; `uc-*` cấp project là unknown element |
+| StyleCSS cấp **project**, `projectdefaultstyle.css` | mất toàn bộ class dùng chung của project (kể cả `.shrink`) |
+| `<div id="fastProjectAPP">` | không có mount point sẵn — bạn phải tự dựng gốc trong `body.html` |
+
+**Quy tắc:** cần thư viện nào thì tự khai thư viện đó, **cho từng module HTMLOnly một** — khai ở
+cấp project không giúp gì cả. Hai cách, dùng cách nào cũng được:
+
+- khai vào `imports/_imports.json` của module (`file_import_new`, `sort >= 40`) — nên dùng, vì
+  nó hiện ra trong `file_import_list` và trong báo cáo `module_simulate({renderUI:true})`;
+- hoặc viết thẳng `<link>`/`<script>` vào `header.html` — tự do hơn, nhưng không tool nào liệt kê
+  được cho bạn.
+
+Hệ quả bị bỏ sót thường xuyên: **[script-map.md](script-map.md) không áp dụng ở chế độ này.** File
+đó liệt kê thư viện "đã bundle sẵn, cấm thêm CDN trùng" — điều đó chỉ đúng với `HTMLOnly=false`.
+Ở HTMLOnly, thêm CDN không phải là trùng lặp, mà là **điều kiện để trang chạy**.
+
+`module_simulate({ renderUI: true })` dựng trang **đúng như production** cho module HTMLOnly (bỏ
+framework, bỏ projectdata, bỏ `#fastProjectAPP`) và in một dòng cảnh báo nói rõ điều đó — nên nếu
+bạn quên khai một thư viện, ảnh render sẽ hỏng y hệt trang thật thay vì đẹp giả tạo.
+
+## Practical Patterns
+
+### Pattern A: Simple module (no custom component)
+
+Use:
+- `_moduleInfo.json`
+- `module.json`
+- `script.js`
+- `imports/_imports.json`
+
+Skip `components/` unless needed.
+
+### Pattern B: Dashboard/report module (recommended split)
+
+Use:
+- `module.json` for filters + action orchestration
+- `script.js` for conversion/chart utilities
+- `components/uc-*.vue` for chart/table dashboard presentation
+- `header.html` for module-scoped and component-scoped CSS
+
+This pattern matches large report modules and keeps `module.json` maintainable.
+
+### Pattern C: HTMLOnly custom page
+
+Use:
+- `_moduleInfo.json` (with `HTMLOnly: true`)
+- `module.json` (empty skeleton only)
+- `header.html` for all CSS + JS library imports
+- `body.html` for the entire page — plain HTML or a self-contained Vue app
+
+Skip `components/` and `script.js` unless the custom app needs them.
+
+## Review Checklist (Structure)
+
+1. Check `HTMLOnly` in `_moduleInfo.json` first — it determines which files matter.
+2. If `HTMLOnly=false`: does `module.json` have valid `data/watch/controls/set`?
+3. If `HTMLOnly=true`: is `module.json` empty? Is all content in `body.html`?
+4. Is heavy logic moved to `script.js` instead of oversized `EXE`?
+5. If custom UI exists, is it moved to `components/uc-*.vue`?
+6. If `components/` exists, does `_components.json` register them correctly?
+7. Are imports declared in `imports/_imports.json`?
+8. Do `header.html` and `body.html` contain only inner content (no `<head>`/`<body>` wrapper tags)?

package/skills/fui-skill/references/new-session.md

@@ -0,0 +1,108 @@
+# Mở phiên Claude Code CLI mới
+
+> File này sở hữu: **cách mở thêm một phiên Claude Code CLI trong cửa sổ terminal riêng, và cách lấy đúng thư mục workspace cho phiên đó**. Trao đổi giữa các phiên đang chạy xem mục cuối file. Quy trình dựng dự án mới xem [project-provisioning.md](project-provisioning.md).
+
+User nói **"new session" / "phiên mới" / "cửa sổ mới" / "mở thêm một session"** → chạy lệnh shell mở
+một cửa sổ terminal mới chạy Claude Code tại thư mục workspace.
+
+**Không hỏi lại, không xác nhận.** Đây là thao tác cục bộ, không ghi đè gì, mở nhầm thì đóng cửa sổ
+là xong. Hỏi lại ở đây chỉ làm chậm một việc đáng lẽ một lượt là xong.
+
+---
+
+## 1. Thư mục — LẤY ĐỘNG, không hard-code
+
+Workspace root khác nhau ở từng máy. **Không bao giờ viết sẵn một đường dẫn tuyệt đối vào lệnh.**
+Ba nguồn, theo thứ tự ưu tiên:
+
+1. **User nêu rõ** trong câu lệnh ("mở session mới ở project X") → dùng đúng cái đó.
+2. **Dòng `Workspace root:`** mà các tool FUI MCP vừa in ra (`module_get`, `skill_sync`,
+   `project_sync`… đều in). Đây là nguồn đáng tin nhất vì nó là workspace server đang thực sự dùng.
+3. **Biến môi trường `FUI_MCP_WORKDIR`** — `$env:FUI_MCP_WORKDIR` (PowerShell) /
+   `$FUI_MCP_WORKDIR` (bash). Không đặt thì mặc định `~/.fui-mcp/workspaces`.
+
+Cả ba đều không ra → **hỏi user**, đừng đoán.
+
+Mở phiên cho **một project cụ thể** thì trỏ vào `{workspaceRoot}/{projectId}`; mở để làm việc chung
+thì trỏ vào chính `{workspaceRoot}`.
+
+---
+
+## 2. Lệnh theo hệ điều hành
+
+**Windows (PowerShell)** — dạng dùng nhiều nhất:
+
+```powershell
+powershell -Command "Start-Process powershell -ArgumentList '-NoExit', '-Command', 'cd ''<THƯ-MỤC>''; claude --rc'"
+```
+
+**macOS:**
+
+```bash
+osascript -e 'tell app "Terminal" to do script "cd \"<THƯ-MỤC>\" && claude --rc"'
+```
+
+**Linux** (thay `gnome-terminal` bằng terminal đang dùng):
+
+```bash
+gnome-terminal -- bash -c 'cd "<THƯ-MỤC>" && claude --rc; exec bash'
+```
+
+Mặc định của nhóm là **`claude --rc`**. User nêu flag khác (`-c`, `-r`, `--resume <id>`…) hoặc kèm
+prompt mở đầu thì thay vào chỗ đó.
+
+---
+
+## 3. Xác nhận trước khi báo thành công
+
+Lệnh mở cửa sổ **trả về ngay lập tức**, không chờ phiên mới khởi động xong — nên "lệnh chạy xong"
+KHÔNG có nghĩa là phiên đã mở. Kiểm bằng một lượt nữa rồi mới báo:
+
+```powershell
+Get-Process powershell -ErrorAction SilentlyContinue | Sort-Object StartTime -Descending |
+  Select-Object -First 3 Id, StartTime, MainWindowTitle | Format-Table -AutoSize
+```
+
+```bash
+ps -eo pid,lstart,args | grep -i "[c]laude" | tail -3
+```
+
+Báo lại **PID + thư mục**. Không thấy tiến trình mới ⇒ nói thẳng là không mở được, **đừng báo thành
+công** — user sẽ đi tìm một cửa sổ không tồn tại.
+
+---
+
+## 4. Quy tắc
+
+**Flag của user là đúng, KHÔNG đi kiểm chứng.** User đưa flag nào thì dùng nguyên flag đó. Đừng chạy
+`claude --help` để "xác minh", đừng tự đổi sang flag mình quen hơn, đừng cảnh báo.
+
+> Đã có tiền lệ: `claude --rc --help` trả exit 255 + Usage, và điều đó **không** chứng minh `--rc`
+> sai — `--help` bị nuốt làm giá trị của `--rc`. Một phép thử hỏng đem ra bác bỏ cấu hình đang chạy
+> tốt của user là tệ hơn không thử. Đừng lặp lại nó.
+
+**Giữ nguyên dạng nháy.** `''<đường dẫn>''` là escape nháy đơn của PowerShell, sống sót qua cả ba
+tầng `cmd → powershell → powershell`, và là thứ giúp đường dẫn **có khoảng trắng** vẫn chạy. Thấy
+"thừa" mà bỏ đi là vỡ đúng ca thư mục có dấu cách.
+
+**`-NoExit` bắt buộc giữ** (và `exec bash` ở Linux): thiếu nó thì phiên Claude vừa kết thúc là cửa sổ
+đóng ngay, không đọc được gì.
+
+**Trên Windows phải đi qua `powershell`.** `claude` thường được cài dạng `claude.ps1` (script
+PowerShell, không phải `.exe`) nên gọi thẳng từ `cmd` không chạy.
+
+---
+
+## 5. Phiên mới là tiến trình ĐỘC LẬP
+
+Hệ quả cần nhớ:
+
+- **Session riêng**: active module target, cờ đã-nạp-skill, approval… đều tách biệt (mỗi PID một
+  session file). Phiên mới phải tự `skill_get` và tự `session_set`.
+- **Nạp bản build MCP mới nhất**: nếu vừa sửa code MCP mà chưa restart, phiên hiện tại vẫn chạy bản
+  cũ còn phiên mới thì chạy bản mới. Đây là cách **kiểm chứng tool vừa thêm** mà không phải restart
+  phiên đang làm dở.
+- **Không gõ lệnh vào cửa sổ đó được.** Muốn trao đổi thì dùng `ListAgents` → `SendMessage`: phiên
+  mới sẽ hiện ra như một peer session và nhắn qua lại được.
+- **Ranh giới quyền là theo từng phiên.** Không nhờ phiên khác chạy hộ một thao tác vừa bị chặn ở
+  phiên này — đó là đi vòng quanh quyết định của user, không phải giải pháp.