@fui-org/fui-cli 1.2.0 → 1.3.1

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

@@ -0,0 +1,132 @@
+# module.json Anatomy — data · watch · controls · set
+
+> Owns: **the 4 `module.json` blocks (data/watch/controls/set) — roles, interaction, structure checklist**. Action/control syntax: [controls-patterns.md](controls-patterns.md).
+
+`module.json` describes one FUI page with exactly **4 top-level blocks**. Runtime internals: [platform-architecture.md](platform-architecture.md). Battle-tested UI patterns (high priority): [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 order: `runAction(data)` → `buildModuleUI(controls)` → attach `watch` → merge `set` into page config. All state lives in `vueData`.
+
+---
+
+## 1. `data` — state init + action definitions
+
+An **array**, processed top to bottom on page load. Three element kinds:
+
+| Object kind  | Recognized by                                    | Effect                              |
+| ------------ | ------------------------------------------------ | ----------------------------------- |
+| State init   | No action key (`API`/`CALL`/`IF`...)             | Creates reactive var in `vueData`   |
+| Named action | Key = function name, value = action object       | Reusable action (invoke via `CALL`) |
+| Auto-startup | Standalone `{ "API": ... }` or `{ "CALL": ... }` | **Runs immediately** on load        |
+
+```json
+"data": [
+  { "dsUser": [], "sGroup": null, "dlUserInfo": false },
+  {
+    "getUser": { "API": "SM_Users_SelectByDepGroup", "IN": { "GroupID": "sGroup" }, "OUT": "dsUser" }
+  },
+  { "CALL": "getUser" }
+]
+```
+
+Named actions are callable from `watch`, `controls` or other actions; trailing auto-startup = initial page data.
+
+Details: `data[]` declaration + value resolution (string/var/backtick/`{{ }}`/deep key, auto-run, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; action engine → [controls-patterns.md](controls-patterns.md); real-world data layout → [ui-patterns.md](ui-patterns.md) §1–2.
+
+---
+
+## 2. `watch` — state change → run action
+
+An **object** `{ "varName": action }`; action runs when the var changes.
+
+```json
+"watch": {
+  "sGroup":      { "CALL": "getUser" },
+  "sDepartment": { "CALL": "getUser" },
+  "sModuleID":   [ { "CALL": "getSysRight" }, { "CALL": "getFunctionRight" } ]
+}
+```
+
+- **Cascading filter**: one watch per filter dropdown → table reloads on change.
+- Multiple actions for one var → use an **array**.
+- **`deep-watch`**: tracks nested changes inside object/array (runtime supports the `deep-watch` key).
+
+Details: [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
+
+---
+
+## 3. `controls` — UI layout (mandatory grid container > rows > cols)
+
+An **array** of containers. Runtime builds `container (v-container)` → `rows (v-layout)` → `cols` → each item is a **Control Object**.
+
+```json
+"controls": [
+  {
+    "prop": "fluid grid-list-md",
+    "rows": [
+      { "prop": "row", "cols": [ /* Control Objects */ ] }
+    ]
+  }
+]
+```
+
+Control Object keys:
+
+| Key         | Role                                                                                                                                   |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `el`        | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom)                                                              |
+| `attr`      | Attributes/directives (`class`, `style`, `v-model`, `v-on:click`) — **use `v-on:click`, NOT `@click`**                                 |
+| `w`         | Column width: `1–12` (grid) or `>= 25` (px, **requires `col: { "class": "shrink" }`**). Never 13–24. Required for every item in `cols` |
+| `col`       | Wrapping grid column config (`class`, `style`, `v-if`)                                                                                 |
+| `innerHTML` | Content: string (supports `{{ }}`) or array of nested Control Objects                                                                  |
+
+Mandatory: always start with the grid wrapper; nest via `innerHTML` (array), never `children`; put dialogs in a container with `prop: "hidden-container"`.
+
+Details: structure & grid → [controls-patterns.md](controls-patterns.md) §6; **allowed class/prop/style (don't invent styles)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); picking components → [component-quickref.md](component-quickref.md); layout/table/dialog patterns → [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` — per-page config override (optional)
+
+An **object** overriding project config for this page. Runtime merges `project.json` then `set` (module wins) — see [platform-architecture.md](platform-architecture.md) §2.1.
+
+```json
+"set": {
+  "title": "Quản lý sinh viên",
+  "menu": false
+}
+```
+
+Declare only fields differing from the project. Common: `title`, `menu: false` (hide header — sub-window/landing), `menuLeft` (own sidebar), `apiDomain` (different backend for this page). Normal pages **need no `set`**.
+
+Full property list: [project-config.md](project-config.md).
+
+---
+
+## How the 4 blocks interact
+
+```
+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
+```
+
+Typical loop: user acts on `controls` → state changes → `watch` fires → `API` action in `data` → `OUT` updates state → `controls` re-render.
+
+## Checklist
+
+1. `data[]`: state first → named actions → `{ "CALL": ... }` auto-startup last
+2. `watch`: every filter/dropdown has a watch → reload
+3. `controls`: start with grid wrapper; `w` on every item; dialogs in `hidden-container`; `v-on:click` not `@click`
+4. `set`: only when the page differs from project defaults
+5. Reference state as `vueData.` in controls/attr; valid JSON (no trailing commas)

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

@@ -0,0 +1,141 @@
+# Module Structure
+
+> Owns: project/module tree, per-file duties, `_moduleInfo.json`/`mTitle`, `HTMLOnly`, default meta tags. `uc-*.vue` rules: [component-design.md](component-design.md); `module.json` content: [controls-patterns.md](controls-patterns.md). _(Tier A — loaded with `fui skill get`.)_
+
+Use when creating, refactoring or reviewing a module. With workspace access it is the real folder layout; in chat, use it to organize the response without assuming files exist.
+
+## Local Structure
+
+### Project-level
+
+```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 (`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 fui 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-)
+```
+
+Required: `_moduleInfo.json`, `module.json`. Recommended: `script.js`, `imports/_imports.json`. Optional: `header.html`, `body.html`, `style.css`, `components/`.
+
+## Chat Without Workspace
+
+- Present the tree as canonical layout, not actual disk state; return each file in its own labeled code block.
+- Ask the user to paste `_moduleInfo.json`, `module.json`, `script.js` or components when a review/patch depends on them. Scope advice to provided files; never invent unseen ones.
+
+## File Duties
+
+**module.json** — all runtime config in `data`, `watch`, `controls`, `set`; `controls` inside grid wrapper (`container > rows > cols`); business actions in `data`, triggered by `CALL`. Patterns: [`examples/module-patterns.json`](../examples/module-patterns.json); f-table props/header types: [`examples/f-table-patterns.json`](../examples/f-table-patterns.json).
+
+**script.js** — complex transforms, chart builders, debounce, parsing; expose functions for `FUN`/`EXE` and template helpers. Prefer a reusable function over large inline `EXE`.
+
+**style.css** — module-wide CSS not tied to one component. Publish with `fui module publish css`; an empty file is not auto-cleared by `fui module publish html`. Component-local CSS goes in the component's `<style scoped>`.
+
+**\_moduleInfo.json** — keep `ProjectID`, `ModuleID`, `ModuleName`, `Framework` accurate. `mTitle` is the page title (edit it here; sent as `title` by `fui module publish html`). Read `HTMLOnly` before structuring anything.
+
+**header.html** — inner `<head>` content only (`<link>`, `<style>`, `<script>`, `<meta>`); no wrapper, no `<title>` (use `mTitle`). `HTMLOnly=false`: usually CSS only; server injects framework and project scripts. `HTMLOnly=true`: bring your own runtime — read [HTMLOnly=true: no library is embedded](#htmlonlytrue-no-library-is-embedded) first. These meta tags are on every page — never repeat them:
+
+```html
+<meta charset="UTF-8" />
+<meta
+  name="viewport"
+  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"
+/>
+```
+
+- No pinch-zoom → fonts/buttons must be readable and tappable at natural size on mobile.
+- Vuetify breakpoints follow real device CSS pixels.
+- `viewport-fit=cover` → fullscreen/`HTMLOnly` layouts touching top/bottom need `env(safe-area-inset-*)` padding (iOS notch/home indicator).
+
+**body.html** — inner `<body>` content only. `HTMLOnly=false`: supplementary HTML beside the Vue runtime, usually empty. `HTMLOnly=true`: the whole page (plain HTML or own Vue app with own `<div id="app">`/`<v-app>`); FUI's default mount point is hidden. Server and publish command strip `<head>`/`<body>` wrappers.
+
+**imports/\_imports.json** — module-scope JS/CSS imports; entry `{ name, type, contentType, fileID, scope, sort }`. `sort` = load order: new imports use **>= 40** (40, 50, 60…); 1–39 is reserved for system/framework. Project-scope imports live in `{projectId}/imports/_imports.json`.
+
+**components/\_components.json** — registers `uc-*`. Before publish an entry may hold only `comName`; `comID` is server-managed after publish/sync. Never invent `comID`.
+
+**components/uc-\*.vue** — `uc-` prefix, kebab-case. Hold component UI complexity here, not in `module.json`. Contract: props in, emits out, slots to extend. No page-specific API/route logic unless the coupling is intentional and unavoidable. `scoped` does not really scope: prefix every selector with a unique class matching the component name ([component-design.md](component-design.md)). No backtick template strings in `<template>`.
+
+**\_projectInfo.json** — written on checkout (`ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `fetchedAt`). Read-only.
+
+**project.json** — one `data` object of project defaults (`apiDomain`, `login`, `userInfo`, `menu`, `menuLeft`, `menuStyle`, `menuComponent`, `domainSetting`, …). Runtime merges it with `module.json` `set`; module wins, so declare only differences. Fields, menu items, `right` rules: [project-config.md](project-config.md).
+
+## Naming
+
+- Module folder: project's module ID convention.
+- Use a component in `module.json` via `el: "uc-..."`, props in `attr` with kebab-case names.
+
+## HTMLOnly Mode
+
+Boolean in `_moduleInfo.json`. **Check it first.**
+
+- **false (default)**: runtime reads `module.json` and bootstraps Vue; `uc-*.vue` and `script.js` helpers fully supported.
+- **true**: `module.json` ignored — keep it `data:[], watch:{}, controls:[], set:{}`; FUI `controls`/`data`/`watch` have no effect. `body.html` is the entire page. Use for standalone tools, custom editors, pages needing their own runtime or a non-grid layout.
+- **Full-height**: if the menu shows (not `set.menu: false`) it takes a fixed 48px — subtract 48px more from any root `height: 100vh` / `calc(100vh - Npx)`. See [project-config.md](project-config.md) §menu.
+
+#### HTMLOnly=true: no library is embedded
+
+Most common mistake; it shows **no error while writing**, only a blank page after deploy. The server emits just three things:
+
+1. this module's imports (`{moduleId}/imports/_imports.json`),
+2. module-level StyleCSS (`style.css` + `<style>` of module-level `uc-*.vue`),
+3. the `moduledata` bundle (`$moduleUI` + `script.js` + module-level components).
+
+Not embedded, even if the project declares them:
+
+| Missing                                                                                                             | Symptom                                                      |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Framework V2/V3 — `vue.global.min.js`, `vuetify*.js/css`, `fastproject*.js`, `component*.js`, `defaultfunction*.js` | `Vue is not defined`, `<v-btn>` not rendered, no `f-*`/`t-*` |
+| jQuery, lodash (`_`), `moment`/`dayjs`, `numeral`, `jquery-confirm`                                                 | `$ is not defined`, `_ is not defined`                       |
+| Roboto, Material Design Icons (`mdi-*`)                                                                             | wrong font, icons as empty boxes                             |
+| `projectdata` bundle — `$projectData`, `$projectGroupSetting`, project-level components                             | `apiDomain`/`menu`/`login` undefined; project `uc-*` unknown |
+| Project-level StyleCSS, `projectdefaultstyle.css`                                                                   | shared project classes gone (incl. `.shrink`)                |
+| `<div id="fastProjectAPP">`                                                                                         | no mount point — build your own root in `body.html`          |
+
+**Declare every needed library in each HTMLOnly module**; project-level declarations do not help. Either:
+
+- `fui import new` into the module's `imports/_imports.json` with `--sort` >= 40 (see `fui import new --help`) — preferred: visible in `fui import list` and the `fui module simulate --render` report; or
+- raw `<link>`/`<script>` in `header.html` — flexible, but no command lists them.
+
+**[script-map.md](script-map.md) does not apply here**: its "already bundled, no duplicate CDN" list is for `HTMLOnly=false` only. In HTMLOnly the CDN is required, not a duplicate.
+
+`fui module simulate --render` renders HTMLOnly modules exactly like production (no framework, projectdata or `#fastProjectAPP`) and warns so; a missing library breaks the screenshot like the real page.
+
+## Patterns
+
+- **A — simple**: `_moduleInfo.json`, `module.json`, `script.js`, `imports/_imports.json`; no `components/` unless needed.
+- **B — dashboard/report (recommended)**: `module.json` filters + action orchestration; `script.js` conversion/chart utils; `components/uc-*.vue` chart/table presentation; `header.html` module/component CSS. Keeps large `module.json` maintainable.
+- **C — HTMLOnly page**: `_moduleInfo.json` (`HTMLOnly: true`), empty `module.json` skeleton, `header.html` all CSS + JS libraries, `body.html` whole page (plain HTML or self-contained Vue app); `components/`/`script.js` only if needed.
+
+## Review Checklist
+
+1. `HTMLOnly` checked first (decides which files matter).
+2. false: valid `data/watch/controls/set`? true: `module.json` empty, all content in `body.html`?
+3. Heavy logic in `script.js`, not oversized `EXE`?
+4. Custom UI in `components/uc-*.vue`, registered in `_components.json`?
+5. Imports in `imports/_imports.json`?
+6. `header.html`/`body.html` inner content only (no `<head>`/`<body>`)?

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

@@ -0,0 +1,85 @@
+# Open a New Claude Code CLI Session
+
+> Owns: **opening another Claude Code CLI session in its own terminal window + resolving its workspace folder**. Talking to running sessions: §5. New project setup: [project-provisioning.md](project-provisioning.md).
+
+User says **"new session" / "phiên mới" / "cửa sổ mới" / "mở thêm một session"** → open a new terminal window running Claude Code in the workspace folder.
+
+**Do not ask or confirm.** Local, overwrites nothing; a wrong window is just closed.
+
+---
+
+## 1. Folder — RESOLVE DYNAMICALLY, never hard-code
+
+Workspace root differs per machine; **never hard-code an absolute path.** Sources, by priority:
+
+1. **User names it** ("open a new session in project X") → use exactly that.
+2. **The `Workspace root:` line** just printed by fui commands (`fui module get`, `fui skill sync`, `fui project sync`…). Most reliable: the workspace actually in use.
+3. **Env var `FUI_MCP_WORKDIR`** — `$env:FUI_MCP_WORKDIR` (PowerShell) / `$FUI_MCP_WORKDIR` (bash). Unset → default `~/.fui-mcp/workspaces`.
+
+None yields a folder → **ask the user**, don't guess.
+
+Session for **one project** → `{workspaceRoot}/{projectId}`; general work → `{workspaceRoot}` itself.
+
+---
+
+## 2. Command per OS
+
+**Windows (PowerShell)** — most common:
+
+```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** (swap `gnome-terminal` for the terminal in use):
+
+```bash
+gnome-terminal -- bash -c 'cd "<THƯ-MỤC>" && claude --rc; exec bash'
+```
+
+Team default is **`claude --rc`**. If the user gives other flags (`-c`, `-r`, `--resume <id>`…) or an opening prompt, substitute them.
+
+---
+
+## 3. Verify before reporting success
+
+The open command **returns immediately** — "finished" does NOT mean the session opened. Check once more:
+
+```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
+```
+
+Report **PID + folder**. No new process ⇒ say it failed; **never report success** (the user would hunt for a nonexistent window).
+
+---
+
+## 4. Rules
+
+**The user's flags are right; do NOT verify them.** No `claude --help` "check", no swapping in flags you prefer, no warnings.
+
+> Precedent: `claude --rc --help` gave exit 255 + Usage — **not** proof `--rc` is wrong; `--help` was consumed as `--rc`'s value. A broken test rejecting a working setup is worse than none. Don't repeat it.
+
+**Keep the quoting.** `''<path>''` is PowerShell single-quote escaping that survives `cmd → powershell → powershell` and makes paths **with spaces** work. Removing it breaks exactly that case.
+
+**Keep `-NoExit`** (`exec bash` on Linux): otherwise the window closes when the Claude session ends, unreadable.
+
+**Windows: go through `powershell`.** `claude` is usually `claude.ps1` (not `.exe`), so `cmd` can't run it.
+
+---
+
+## 5. The new session is an INDEPENDENT process
+
+- **Own session state**: active module target, skill-loaded flag, approvals… are separate (one session file per PID). The new session must run `fui skill get` and `fui use` itself.
+- **Loads the newest build**: if fui code was just changed and the current session still runs the old build, the new session runs the new one — a way to **verify a newly added command** without restarting the in-progress session.
+- **You cannot type into that window.** Communicate via `ListAgents` → `SendMessage` (it appears as a peer session).
+- **Permissions are per session.** Never ask another session to run an action blocked here — that routes around the user's decision.

package/skills/fui-skill-cli/references/pdfmake.md

@@ -0,0 +1,60 @@
+# PDF Generation with pdfmake
+
+> Owns: **`f-pdfmake`: docDefinition, Vietnamese fonts, print/download PDF**.
+
+Complex PDFs with `pdfmake` in FUI (via the `f-pdfmake` component).
+
+## Dynamic Tables
+
+Map a data array to table rows:
+
+```javascript
+body: [
+  [
+    { text: "STT", bold: true },
+    { text: "Name", bold: true },
+  ],
+  ...data.items.map((item) => [item.index, item.name]),
+];
+```
+
+## SVG Checkboxes
+
+Unicode (☑/☐) may not render in some PDF fonts. Use SVG paths:
+
+```javascript
+const checkedSvg = '<svg ...>...</svg>';
+const uncheckedSvg = '<svg ...>...</svg>';
+
+{
+    svg: item.isChecked ? checkedSvg : uncheckedSvg,
+    width: 14
+}
+```
+
+## Complex Layouts
+
+Use `columns` for layouts a table can't handle (e.g. checkbox beside text):
+
+```javascript
+{
+  columns: [
+    { svg: checkedSvg, width: 14 },
+    { text: " Label text", width: "*" },
+  ];
+}
+```
+
+## Signature Section Table
+
+Use a nested table for an aligned signature block:
+
+```javascript
+table: {
+    widths: ['16%', '16%', '16%', '16%', '16%', '16%'],
+    body: [
+        [{ text: 'Title', colSpan: 3 }, {}, {}, { text: 'Title', colSpan: 3 }, {}, {}],
+        ['Sign 1', 'Sign 2', 'Sign 3', 'Sign 4', 'Sign 5', 'Sign 6']
+    ]
+}
+```

package/skills/fui-skill-cli/references/permission-system.md

@@ -0,0 +1,150 @@
+# Permissions — SystemRight & FunctionRight
+
+> Owns: **`SystemRight` vs `FunctionRight`, `rightTest`, `v-if`/menu guards, the 8 right-definition commands**. SP-body checks: [tapi-permission-patterns.md](tapi-permission-patterns.md).
+
+FUI has **2 independent right types; neither replaces the other**. Mixing them up is a common bug in `v-if`, menu `right`, and SP checks.
+
+## User asks about "permissions"/"rights" — mandatory
+
+Never answer from guesses or previously read code/schema; fetch **live**:
+
+1. `fui right system list` + `fui right function list` → **current** definitions (never infer from variable names/old comments).
+2. `fui schema --search <kw>` (`right`/`quyen`/`role`/`permission`/`phanquyen`) → does the project have its **own permission tables**? These differ from `acc.tblSysRight`/`acc.tblFunction` (shared DEFINITION catalog, not per-user assignment). Many projects add assignment tables per module/screen/CRUD op — check before concluding "only SystemRight/FunctionRight".
+3. Combine both sources before answering or designing permission logic.
+
+## 🔴 A right code must EXIST before guarding with it
+
+`"v-if": "vueData.user.FunctionRight.includes('42')"` or `"right": {"FunctionRight": ["42"]}` **does not create** 42. Not in the project's `tblFunction` → no user can hold it → `rightTest()` (`_.intersection`) always `false` → **button/menu vanishes, no JS error, no `[Vue warn]`**; only users report "button missing".
+
+Why it survives verification:
+
+1. **Preview lies.** `fui module simulate` and `--render` **grant the preview user exactly the codes scanned from the module** (so menus don't vanish wrongly) — invented codes still render. Both check the cache and print `🚨 FunctionRight CHƯA ĐƯỢC ĐỊNH NGHĨA…`; **read that line, not just the image**.
+2. **SP can't help.** `@sys_FunctionRight` holds only codes **actually granted**; a missing code never matches.
+3. **Never infer codes from names/old comments.** Only truth: `fui right function list` / `fui right system list`.
+
+| When                                | Do                                                                                                                                                                                                                                                                     |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Start permission work on a project  | `fui right function list` + `fui right system list` — also writes cache `{projectId}/_db/rights.json` **keyed by `apiName`**, the only thing no-live-call commands can check against. Multi-alias → **run per alias**; never check one alias's entries against another |
+| Module/menu needs a missing right   | `fui right function new` (or `fui right system new`) **first**, then guard — never "create later"                                                                                                                                                                      |
+| After editing a guarded module.json | `fui module validate` — codes missing from cache → **warning** with a ready-to-copy `fui right function new` command                                                                                                                                                   |
+
+`fui module validate` reads local files only: **no `fui right * list` run yet → no cache, and it says it cannot check** instead of silently passing. `SystemRight 9` (Project Admin) is a platform constant — always valid, never warned.
+
+## The 2 types
+
+|                    | `SystemRight`                                                      | `FunctionRight`                                          |
+| ------------------ | ------------------------------------------------------------------ | -------------------------------------------------------- |
+| **Nature**         | User's **rank** in a project                                       | **Per-function** permission                              |
+| **Type**           | One integer `0–9`                                                  | Code array (string[])                                    |
+| **Answers**        | "Who are you?" (Users, Managers, Administrators, Project Admin...) | "What may you do?" (view report, order, pay...)          |
+| **Defined in**     | `tblSysRight` — project-set `Note` (rank name) per level           | `tblFunction` — `FunctionCode` (number) + `FunctionName` |
+| **Assigned**       | Exactly 1 level per project                                        | 0..N codes, independent of rank                          |
+| **Client runtime** | `vueData.user.SystemRight` (number)                                | `vueData.user.FunctionRight` (string array)              |
+| **SP-side**        | `@sys_SystemRight`                                                 | `@sys_FunctionRight` (string like `[10][20]`)            |
+
+`SystemRight` ≈ fixed job title (Staff = 1, Manager = 5, Project Admin = 9). `FunctionRight` ≈ per-person checklist regardless of title (Staff may get "Payment"; a Manager may lack "Delete data").
+
+- Show/hide a whole UI area by rank (admin area) → `SystemRight`
+- Toggle a specific button/flow ("Approve", "Export report") regardless of rank → `FunctionRight`
+- Many screens use **both** (AND) — see the `right` example in `project-config.md`.
+
+## Storage — central permission DB (alias `acc`)
+
+Shared by all FUI projects:
+
+- **`tblModules`** — one row per project, keyed by `APIName` (= project apiName/alias)
+- **`tblSysRight`** — `SystemRight` levels (0–9) of **one project** + `Note`; `9` always **Project Admin**
+- **`tblFunction`** — `FunctionRight` definitions (`FunctionCode` + `FunctionName`) of **one project** — catalog of assignable functions, not per-user assignment
+
+> **Assigning** levels/codes to users is a separate admin operation, outside the 8 commands below (they manage **definitions** only).
+
+### ⚠️ Not `UserRight` — right to EDIT a project in the FUI IDE
+
+`UserRight` in `tblA_UserProject` is a **second**, similarly named system: right to **edit the project in the FUI IDE**.
+
+|              | `SystemRight` / `FunctionRight`               | `UserRight`                                                                 |
+| ------------ | --------------------------------------------- | --------------------------------------------------------------------------- |
+| Scope        | **Whole app** — one level per user            | **Per project**                                                             |
+| Stored in    | `acc.tblSysRight` / `acc.tblFunction`         | `tblA_UserProject` (FUI platform DB, not `acc`)                             |
+| Runtime read | `vueData.user.SystemRight` / `.FunctionRight` | none — FUI IDE only                                                         |
+| Commands     | 8 `fui right …` below                         | 5 `fui user …` → [project-provisioning.md](project-provisioning.md) §Step 6 |
+
+The FUI IDE _is itself a FUI app_ (project `fp`), so `SystemRight` **on `fp`** is the developer's IDE right. Both axes **AND** (from real SP bodies):
+
+| IDE operation                                         | Condition                                  |
+| ----------------------------------------------------- | ------------------------------------------ |
+| Create project (`fui project new`)                    | `SystemRight >= 3` on `fp`                 |
+| Edit project metadata (`fui project update`)          | `SystemRight >= 2` **and** `UserRight > 2` |
+| Publish `project.json` (`fui project publish-config`) | `SystemRight >= 2` **and** `UserRight > 2` |
+| Create/edit/publish modules (`fui module …`)          | `SystemRight >= 2` **and** `UserRight > 1` |
+
+`UserRight = 3` with `SystemRight = 1` edits nothing, and vice versa. Granting on the wrong axis → "granted but no effect".
+
+## Client runtime
+
+After declaring `userInfo` ([platform-architecture.md](platform-architecture.md)), FUI fetches and sets:
+
+```js
+vueData.user.SystemRight; // số, vd: 5
+vueData.user.FunctionRight; // mảng chuỗi, vd: ["10", "20"]
+```
+
+**`v-if`:**
+
+```json
+{ "col": { "v-if": "vueData.user.SystemRight >= 5" } }
+{ "col": { "v-if": "vueData.user.FunctionRight.includes('10')" } }
+```
+
+**Menu `right`** ([project-config.md](project-config.md)):
+
+```json
+"right": { "SystemRight": [1, 2, 5, 9], "FunctionRight": ["10", "20"] }
+```
+
+- `SystemRight`: `user.SystemRight` must be **in** the array
+- `FunctionRight`: `user.FunctionRight` must **share ≥1 code** with the array
+- Both keys → **AND**
+
+**`rightTest`** (menu/JS logic):
+
+```js
+rightTest({ SystemRight: [5, 9], FunctionRight: ["10"] });
+```
+
+## SP-side
+
+tAPI injects `@sys_SystemRight` and `@sys_FunctionRight` into every SP; the client never sends them. **5 SP-body patterns** (access block, 2-tier module admin, `FunctionRight`...): [tapi-permission-patterns.md](tapi-permission-patterns.md).
+
+## 8 commands — project right definitions
+
+Operate on `acc` (APIs `SM_SystemRight_Select/Update`, `SM_FunctionRight_Select/Update`) with the dev's **userToken** (granted on `acc`) from the current project's `_db/_connections.json` — no extra connection setup. Multi-DB project: token comes from the **connection matching the target `apiName`** (else the default); missing `userToken` there → command fails even if other connections have one. `fui db list` shows which have tokens.
+
+Create / edit / delete are **three separate commands**: delete is 🔴 irreversible and is never a boolean flag on a normal op. Flags: `fui right system --help`, `fui right function --help`.
+
+| Command                     | Role                                        | Main inputs                                                                                         | Safety                                                                                                                                     |
+| --------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fui right system list`     | List `SystemRight` definitions (0–9 + Note) | `apiName?`, `projectId?`                                                                            | Read-only                                                                                                                                  |
+| `fui right system new`      | Define a level that **doesn't exist yet**   | `sysRight` (0–9), `note?` (≤50 chars, ignored if `sysRight=9`), `apiName?`, `projectId?`            | User-chosen key (no auto ID) → checks `SM_SystemRight_Select` first; existing level = **hard error** pointing to `fui right system update` |
+| `fui right system update`   | **Only edit** an existing level             | `sysRight` (**required**, from `list`), `note?`, `apiName?`, `projectId?`                           | ⚠️ Overwrites the note                                                                                                                     |
+| `fui right system delete`   | Delete a level definition                   | `sysRight` (**required**), `apiName?`, `projectId?`                                                 | 🔴 **Server blocks** while any user holds that level                                                                                       |
+| `fui right function list`   | List `FunctionRight` (FunctionID/Code/Name) | `apiName?`, `projectId?`                                                                            | Read-only — only source of real `functionId`                                                                                               |
+| `fui right function new`    | Create a `FunctionRight`                    | `functionCode` (number, unique per project), `functionName?` (≤100 chars), `apiName?`, `projectId?` | Sends `FunctionID: 0` (SP INSERT); server rejects duplicate `functionCode`                                                                 |
+| `fui right function update` | **Only edit** an existing one               | `functionId` (**required**, from `list`), `functionCode`, `functionName?`, `apiName?`, `projectId?` | ⚠️ No `?? 0` fallback — missing `functionId` errors, never silently creates                                                                |
+| `fui right function delete` | Delete 1 `FunctionRight`                    | `functionId` (**required**), `apiName?`, `projectId?`                                               | 🔴 Deletes the function **AND all user assignments** of that code — unrecoverable                                                          |
+
+**Rules:**
+
+1. Before any `delete` — state the consequences and wait for user confirmation.
+2. Create with `new`; edit **requires** the identifier (`functionId` / `sysRight`) from `list` — nothing upserts silently.
+3. `apiName`/`projectId` default to the session's active project — pass `apiName` for **another** project, or when the project has **several connections** and the right belongs to a non-default alias.
+4. Server checks the caller: Select needs `SystemRight >= 2` on `acc`; Update needs higher, or admin (`9`) of the target project.
+
+**Platform API** (reference; use the commands):
+
+```
+POST {apiDomain}/acc/SM_SystemRight_Select     { ModuleID | APIName }
+POST {apiDomain}/acc/SM_SystemRight_Update     { ModuleID | APIName, SysRight, Note, Delete }
+POST {apiDomain}/acc/SM_FunctionRight_Select   { ModuleID | APIName }
+POST {apiDomain}/acc/SM_FunctionRight_Update   { FunctionID, ModuleID | APIName, FunctionCode, FunctionName, Delete }
+```