@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill-cli/references/tapi-reference.md

@@ -1,474 +0,0 @@
-# tAPI Reference — Transparent Query API (Core)
-
-> Owns: **tAPI conventions: SP naming (`spAPI_*`/`spAPI_AUTH_*`/`spAPIFILE_*`), params, URL, response contract, `/help` route**. Deploy workflow: [db-workflow.md](db-workflow.md).
-
-tAPI auto-generates APIs from SQL SPs; the SP name sets URL, auth type and access (no controllers/routes). Accepts **GET and POST** — don't specify a method in the SP; module.json picks it. Load as needed:
-
-| Topic                                                                           | File                                                       |
-| ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| Permission checks in SP body (5 patterns, `@sys_SystemRight`, `getSystemRight`) | [tapi-permission-patterns.md](tapi-permission-patterns.md) |
-| File API — GET/UPLOAD, `spAPIFILE_`, `fileContent`, `tblFileData`               | [tapi-file-api.md](tapi-file-api.md)                       |
-
-> Image processing, outbound HTTP, email, server file I/O, regex → first check for an existing **SQL CLR function** (`httpCall`, `sendMail`, `ImageResize`, `FileWriter`, `RegexMatch`...): [sql-clr-functions.md](sql-clr-functions.md).
-
-## 1. SP naming
-
-```
-spAPI_[AUTH_]FunctionName
-```
-
-| Part           | Required | Meaning                                                          |
-| -------------- | -------- | ---------------------------------------------------------------- |
-| `spAPI_`       | ✅       | Marks SP as API-callable. Missing → API cannot call it           |
-| `AUTH_`        | ❌       | No auth required. Omitted → valid token mandatory                |
-| `FunctionName` | ✅       | API function name used in URL, e.g. `MessageHome`, `UserSetting` |
-
-```sql
-spAPI_MessageHome       -- có auth
-spAPI_AUTH_SelectChat   -- không cần auth
-```
-
-File API:
-
-```
-spAPIFILE_Document         -- SP để GET file
-spAPIFILE_UPLOAD_Document  -- SP để nhận file upload
-```
-
-Details: [tapi-file-api.md](tapi-file-api.md).
-
----
-
-## 2. SP parameters
-
-### `@url1_`, `@url2_`, `@url3_`... — route params
-
-Taken from URL segments in order:
-
-```
-https://api.domain.vn/app/FunctionName/value1/value2
-```
-
-```sql
-@url1_GroupID varchar(50),  -- nhận "value1"
-@url2_Mode    varchar(50),  -- nhận "value2"
-```
-
-### `@sys_` — system params (injected by tAPI, never sent by client)
-
-| Param                      | Type          | Meaning                                                                                                      |
-| -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
-| `@sys_UserID`              | varchar(9)    | Authenticated user ID                                                                                        |
-| `@sys_UserName`            | varchar(50)   | Login name                                                                                                   |
-| `@sys_GroupID`             | int           | User's group                                                                                                 |
-| `@sys_DepartmentID`        | varchar(9)    | Department ID                                                                                                |
-| `@sys_SystemRight`         | int           | Tiered right (1=low, 9=high)                                                                                 |
-| `@sys_FunctionRight`       | varchar(2000) | Function rights as `[AD][RPT][MGR]`                                                                          |
-| `@sys_SessionID`           | varchar(50)   | Auth session ID                                                                                              |
-| `@sys_RawData`             | nvarchar(max) | Full client JSON body                                                                                        |
-| `@sys_header_{HeaderName}` | varchar(n)    | **A family, not one fixed name** — reads any HTTP header; `NULL` if client didn't send it. Naming rule below |
-
-> **CRITICAL — never put `@sys_` in module.json `IN`.** tAPI fills all `@sys_*` from the session; client values are **ignored or overwritten**.
->
-> ```json
-> // ❌ SAI — không đưa sys_ vào IN
-> "IN": { "ModuleID": "sModuleID", "sys_UserID": "vueData.user.UserID" }
->
-> // ✅ ĐÚNG — chỉ truyền custom params
-> "IN": { "ModuleID": "sModuleID" }
-> ```
-
-#### `@sys_header_*` — read HTTP headers: replace each `-` with `_`
-
-Works for **any** header. `-` is invalid in SQL Server param names, so the literal name won't compile:
-
-```sql
--- ❌ SAI — lỗi cú pháp ngay lúc CREATE PROCEDURE, không phải lỗi runtime
-@sys_header_User-Agent   varchar(500)
-```
-
-- **No quoting works**: `@[sys_header_User-Agent]` and `@"sys_header_User-Agent"` are both invalid. Renaming is the **only** way.
-- **Each `-` → one `_`.** 1-to-1: don't drop characters, change case, or merge segments.
-
-| HTTP header        | SP param                                 |
-| ------------------ | ---------------------------------------- |
-| `User-Agent`       | `@sys_header_User_Agent`                 |
-| `Sec-Ch-Ua-Mobile` | `@sys_header_Sec_Ch_Ua_Mobile`           |
-| `X-Forwarded-For`  | `@sys_header_X_Forwarded_For`            |
-| `Accept-Language`  | `@sys_header_Accept_Language`            |
-| `Cookie`           | `@sys_header_Cookie` — no `-`, unchanged |
-
-- Reverse (reading an existing SP): drop `@sys_header_`, turn remaining `_` into `-` — `@sys_header_Accept_Language` → `Accept-Language`.
-- Matching is **case-insensitive** (prefix and name): `@sys_header_User_Agent`, `@sys_Header_User_Agent`, `@sys_header_USER_AGENT` are the same header (so `@sys_Header_RequestID` works). Still use standard casing (`User-Agent`, not `USER_AGENT`). Only `_` for `-` is mandatory.
-
-```sql
-CREATE PROCEDURE spAPI_AuditLog_Insert
-    @Action                     nvarchar(100),
-    @sys_UserID                 varchar(9),
-    @sys_header_User_Agent      nvarchar(500),
-    @sys_header_X_Forwarded_For varchar(200)
-AS
-BEGIN
-    -- ISNULL vì client không gửi header thì tham số là NULL, không phải chuỗi rỗng
-    INSERT INTO tblAuditLog (Action, UserID, UserAgent, ClientIP, CreateTime)
-    VALUES (@Action, @sys_UserID,
-            ISNULL(@sys_header_User_Agent, N'(không có)'),
-            ISNULL(@sys_header_X_Forwarded_For, ''),
-            GETDATE());
-END
-```
-
-- **Still `@sys_*`:** auto-filled, **not** in `IN`, **no default** (`= null` is a hard error; `fui sp deploy` blocks it, see below).
-- **Missing header → `NULL`** (not `''`) — normal, e.g. script/server-to-server calls often lack `User-Agent`. Wrap in `ISNULL(...)` at use: comparisons give UNKNOWN (`WHERE @sys_header_User_Agent <> 'bot'` **drops** the row), and `+` concatenation gives `NULL` (blanks the whole log string).
-- **Untrusted (client-supplied, spoofable).** Log/stats only, never authorization; take rights from `@sys_UserID`/`@sys_SystemRight` (from the verified token).
-
-Check the name tAPI sees: `fui sp help <name>` (§3.1).
-
-### Custom params — business params
-
-Param name = JSON body field name:
-
-```sql
-@StudentID  varchar(9),
-@SemesterID int,
-@Keyword    nvarchar(200)
-```
-
-#### Param binding is LENIENT — never errors
-
-- Body **lacks** a key → param gets **`NULL`**. Body has an **extra** key → **silently ignored**.
-- A typo in `IN` (`StudentId` vs `StudentID`) → SP gets `NULL`, empty/wrong data, HTTP 200. Most common silent wiring bug.
-- **Renaming/removing an SP param is a contract change with NO signal**: old modules keep sending old keys. Audit callers or compare with `fui sp help <name>` (§3.1).
-- **`NULL` follows T-SQL rules** (`<>` → UNKNOWN drops rows; `+` → `NULL`): wrap possibly-absent params in `ISNULL(...)` at use.
-
-> **CRITICAL — no default value on any param** (`= value` or `= null`, including `@sys_*`). tAPI **always passes every param** (`NULL` if not sent), so `@HeID int = 99` silently gives `NULL`, not `99`. `fui sp deploy` hard-blocks it for `spAPI_*`/`spAPIFILE_*` (`detectDefaultApiParams()` in `src/tools/db.ts`); `fui sp verify` warns earlier. Set defaults **in the body**: `SET @HeID = ISNULL(@HeID, 99)`.
->
-> ```sql
-> -- ❌ SAI
-> CREATE PROCEDURE spAPI_TS_Report
->     @HeID          int = 99,
->     @NamHoc        int = 2024,
->     @sys_UserID    varchar(9) = null,
->     @sys_SystemRight int
->
-> -- ✅ ĐÚNG
-> CREATE PROCEDURE spAPI_TS_Report
->     @HeID          int,
->     @NamHoc        int,
->     @sys_UserID    varchar(9),
->     @sys_SystemRight int
-> ```
-
-Client sends: `POST /app/FunctionName` with body `{ "StudentID": "SV001", "SemesterID": 1 }`
-
----
-
-## 3. API URL
-
-```
-{domain}/{apiName}/{FunctionName}/{url1}/{url2}...
-{domain}/{apiName}/auth/{FunctionName}/{url1}/{url2}...
-```
-
-| Part              | Meaning                                                                                                         |
-| ----------------- | --------------------------------------------------------------------------------------------------------------- |
-| `domain`          | API domain, e.g. `https://api.example.vn`                                                                       |
-| `apiName`         | App apiName: `me`, `congvan`, `calen`... — also the **DB connection alias** in the workspace (`_db/{apiName}/`) |
-| `auth`            | Add when SP has `AUTH_` (no token)                                                                              |
-| `FunctionName`    | SP name after the prefix                                                                                        |
-| `url1`, `url2`... | Route params for `@url1_`, `@url2_`                                                                             |
-
-**A project can have MANY `apiName`s** (one DB alias each). `"API": "/{alias}/Ten"` in module.json names the SP's database; fui uses that alias for `_db/{alias}/` and as `--db` of DB commands ([db-workflow.md](db-workflow.md) §1, §4).
-
-```
-SP:  spAPI_AUTH_Select_Chat
-URL: https://api.example.vn/me/auth/Select_Chat
-
-SP:  spAPI_GetStudentList
-URL: https://api.example.vn/me/GetStudentList
-
-SP:  spAPI_GetStudentDetail  (@url1_StudentID)
-URL: https://api.example.vn/me/GetStudentDetail/SV001
-```
-
-> **CRITICAL — common bug: missing `/` between `domain` and `apiName`.** `domain` NEVER ends with `/`; insert exactly ONE `/` before `apiName`.
->
-> ```
-> domain=tapi.lhu.edu.vn, apiName=ts, function=TS_Report_HeXetTuyenSelectAll
->
-> ❌ SAI (thiếu /, "ts" bị nuốt vào domain): https://tapi.lhu.edu.vnts/TS_Report_HeXetTuyenSelectAll
-> ✅ ĐÚNG:                                   https://tapi.lhu.edu.vn/ts/TS_Report_HeXetTuyenSelectAll
-> ```
->
-> **Don't build URLs by hand/memory** — copy the `Wiring URL: ...` line from `fui sp verify` (or `fui sp help`) verbatim.
-
-### 3.1 Param cache & `/help` route
-
-tAPI **caches each function's param signature** after the first call. After ALTERing a `spAPI_*`/`spAPIFILE_*` SP's params (add/remove/rename/retype), the live endpoint keeps the **old** signature until cleared. Route = API URL with `/help` right after domain:
-
-```
-{domain}/help/{apiName}/{FunctionName}          ← xoá cache + trả về tham số của hàm
-{domain}/help/{apiName}/auth/{FunctionName}
-```
-
-It **(a) clears the cache** and **(b) returns the input params** (useful before wiring `IN`).
-
-**Mandatory after every SP ALTER/UPDATE** (else old signature → param errors even with a correct SP):
-
-- `fui sp deploy` auto-calls `/help` **once, standard URL; ignore failure** (SP is already deployed).
-- `ALTER PROCEDURE` via `fui exec`: **no auto-clear → run `fui sp help` manually** right after. The only manual case.
-- **`/help` errors → STOP, no URL variants.** `/auth/` or not follows from the SP name; retrying changes nothing. Re-run `fui sp help` only if the live endpoint truly still takes old params.
-
----
-
-## 4. Response format
-
-### 4.1 One SELECT → array
-
-```sql
-SELECT StudentID, FullName, GPA FROM tblStudent WHERE ClassID = @ClassID
-```
-
-```json
-{
-  "data": [
-    { "StudentID": "SV001", "FullName": "Nguyen Van A", "GPA": 3.5 },
-    { "StudentID": "SV002", "FullName": "Tran Thi B", "GPA": 3.2 }
-  ]
-}
-```
-
-### 4.2 Multiple SELECTs → array of arrays
-
-Each `SELECT` becomes one sub-array in `data`:
-
-```sql
-SELECT TotalCount = COUNT(*) FROM tblStudent WHERE ClassID = @ClassID
-SELECT StudentID, FullName FROM tblStudent WHERE ClassID = @ClassID
-```
-
-```json
-{
-  "data": [
-    [{ "TotalCount": 42 }],
-    [
-      { "StudentID": "SV001", "FullName": "Nguyen Van A" },
-      { "StudentID": "SV002", "FullName": "Tran Thi B" }
-    ]
-  ]
-}
-```
-
-In module.json, read sub-arrays by index:
-
-```json
-"OUT": "studentList",
-"CALLBACK": { "EXE": "vueData.total = vueData.studentList[0][0].TotalCount; vueData.students = vueData.studentList[1]" }
-```
-
-### 4.3 `convert_to_object` — row → object
-
-Returns an object instead of an array. **Many SELECTs** may use it; all merge into one response object.
-
-> ⚠️ When a SELECT has `convert_to_object` **and** a `json_data` column with a JSON string, it must return **exactly 1 row**. More than 1 → tAPI returns `{}`.
-
-- `convert_to_object = 'key'` → nested object under that key
-- `convert_to_object = ''` → merged into root
-
-**Ex 1 — named key + root merge:**
-
-```sql
-SELECT convert_to_object = 'sinhvien',
-       sys_SystemRight = @sys_SystemRight,
-       sys_FunctionRight = @sys_FunctionRight
-
-SELECT convert_to_object = '',
-       ngaythang = GETDATE(), count = 10
-```
-
-```json
-{
-  "sinhvien": {
-    "sys_SystemRight": 9,
-    "sys_FunctionRight": "[11][3]"
-  },
-  "ngaythang": "2018-09-11T11:20:47.397",
-  "count": 10
-}
-```
-
-**Ex 2 — `json_data` overrides same-name fields** (parsed and merged after SQL columns, so `json_data` wins, e.g. `ProjectName`):
-
-```sql
-SELECT convert_to_object = '',
-       ProjectName = N'abc',
-       stt = 123,
-       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
-```
-
-```json
-{
-  "ProjectName": "T-A-P-I",
-  "stt": 123,
-  "menu": [
-    { "name": "Croatia", "link": "vn" },
-    { "name": "England", "link": "/tuyensinh" }
-  ]
-}
-```
-
-**Ex 3 — multiple `convert_to_object = ''` SELECTs all merge into root:**
-
-```sql
-SELECT convert_to_object = '',
-       ProjectName = N'abc', stt = 123,
-       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
-
-SELECT convert_to_object = '',
-       TruyVan2 = N'Dữ liệu của truy vấn 2',
-       json_data = '{"TruyVan2_json_string": 99}'
-```
-
-```json
-{
-  "ProjectName": "T-A-P-I",
-  "stt": 123,
-  "menu": [
-    { "name": "Croatia", "link": "vn" },
-    { "name": "England", "link": "/tuyensinh" }
-  ],
-  "TruyVan2": "Dữ liệu của truy vấn 2",
-  "TruyVan2_json_string": 99
-}
-```
-
-### 4.4 `[json_data:FieldName]` — JSON string column → object
-
-Return a JSON-string column as an object:
-
-```sql
-SELECT PartID, PartName, [json_data:FileInfo] = FileInfo
-FROM tblPart WHERE PartID = @url1_PartID
-```
-
-tAPI parses it into a nested object:
-
-```json
-{
-  "PartID": "P001",
-  "PartName": "Tài liệu",
-  "FileInfo": { "fileName": "doc.pdf", "size": 1024 }
-}
-```
-
-DB column stays a string. Name after `:` = response field; after `=` = real column.
-
----
-
-## 5. Error handling in SP
-
-All errors use `RAISERROR` with severity **16**.
-
-### Normal errors (validation, data constraints)
-
-```sql
-RAISERROR(N'Dữ liệu không hợp lệ', 16, 1)
-RETURN
-```
-
-```json
-{ "Message": "Dữ liệu không hợp lệ" }
-```
-
-### Unauthorized — prefix `[Unauthorized]` → HTTP 401
-
-```sql
-IF @sys_SystemRight < 2
-BEGIN
-    RAISERROR(N'[Unauthorized]Bạn không có quyền trên chức năng này.', 16, 1)
-    RETURN
-END
-```
-
-```json
-{ "Message": "Bạn không có quyền trên chức năng này." }
-```
-
-**Mandatory:**
-
-- Always severity `16` — never `11`, `14` or anything else.
-- Always `RETURN` right after `RAISERROR`.
-- `N` prefix required for Vietnamese Unicode.
-- **Every permission error (missing `SystemRight`/`FunctionRight`) must start with `[Unauthorized]`** → HTTP `401` instead of `200`/`500`; client `errorMess()` (`fastproject.js`) redirects to login if message contains "token", else shows a permission error. tAPI strips the prefix from `Message`. Validation errors **don't** use it.
-
-> Detailed permission checks (5 patterns, `getSystemRight`, check order, message conventions): [tapi-permission-patterns.md](tapi-permission-patterns.md).
-
----
-
-## 6. SP design rules
-
-### Naming
-
-```
-spAPI_{Entity}{Action}
-```
-
-| Action              | Meaning                 |
-| ------------------- | ----------------------- |
-| `Select` / `List`   | List query              |
-| `Get`               | One record's detail     |
-| `Insert` / `Add`    | Create                  |
-| `Update` / `Edit`   | Update                  |
-| `Delete` / `Remove` | Delete                  |
-| `AUTH_Select`       | Public query (no token) |
-
-```sql
-spAPI_StudentList          -- GET danh sách sinh viên
-spAPI_StudentGet           -- GET chi tiết (url1 = StudentID)
-spAPI_StudentInsert        -- POST thêm mới
-spAPI_StudentUpdate        -- POST cập nhật
-spAPI_StudentDelete        -- POST xoá (url1 = StudentID)
-spAPI_AUTH_CourseList      -- Danh sách môn học công khai
-```
-
-### Wiring in FUI module.json
-
-```json
-"fetchStudents": {
-  "API": "/me/StudentList",
-  "IN": { "Keyword": "vueData.keyword", "ClassID": "vueData.selectedClass" },
-  "OUT": "studentList"
-},
-"addStudent": {
-  "API": "/me/StudentInsert",
-  "IN": {
-    "StudentID":  "vueData.form.StudentID",
-    "FullName":   "vueData.form.FullName",
-    "ClassID":    "vueData.form.ClassID"
-  },
-  "CALLBACK": [ { "CALL": "vueData.fetchStudents" }, { "MESS": "Đã thêm thành công" } ]
-},
-"deleteStudent": {
-  "API": "/me/StudentDelete/`{{vueData.selectedID}}",
-  "CONFIRM": "Bạn có chắc muốn xoá?",
-  "CALLBACK": { "CALL": "vueData.fetchStudents" }
-}
-```
-
----
-
-## 7. SP design checklist
-
-1. `spAPI_` prefix mandatory — missing means API can't call it.
-2. Add `AUTH_` for public endpoints (login page, lookup data).
-3. Always include `@sys_UserID` in SPs that write data (audit trail).
-4. No `SELECT *` — list columns.
-5. Check permissions at SP start if needed, with `RAISERROR` + `RETURN` — see [tapi-permission-patterns.md](tapi-permission-patterns.md).
-6. Multiple SELECTs → client reads by index `data[0]`, `data[1]`.
-7. Single record → use `convert_to_object` instead of `data[0][0]`.
-8. **No `GRANT EXECUTE` in the .sql file** — the SP body runs to end of batch and tAPI has no `GO` support, so a GRANT after `END` is **swallowed into the SP body** (runs every call, grants nothing, no error). `fui sp deploy` grants and confirms via `sys.database_permissions` — read its `✓`/`❗` line ([verification.md](verification.md#security)).
-9. **Never put `sys_*` params in module.json `IN`** — tAPI injects them.
-   9b. **Headers** → `@sys_header_{HeaderName}`, **each `-` → `_`**; `-` is a syntax error, brackets don't help (§2). Log only, never gate permissions.
-   9c. **Binding never errors** (missing → `NULL`, extra → ignored): check `IN` names with `fui sp help`. `DEFAULT` is useless; use `SET @x = ISNULL(@x, <giá trị>)`.
-10. **File GET/UPLOAD**: prefix `spAPIFILE_`, binary column alias `fileContent`, params `@sys_FileContent`/`@sys_FileName`, standard table `tblFileData` — see [tapi-file-api.md](tapi-file-api.md). Don't infer from training data.
-11. **Any ALTER/UPDATE of a deployed SP** (params, logic, anything) → **MUST clear tAPI cache** via `fui sp help` (§3.1). `fui sp deploy` does it (once; ignore failure); only ALTER via `fui exec` needs it manually.

package/skills/fui-skill-cli/references/tools-registry.md

@@ -1,84 +0,0 @@
-# fui commands — safety registry
-
-Risk per command. `R` reads only (touches no byte on disk); `M` writes the server or the local workspace (a local refresh overwrites files; the old copy goes to `_history/` first).
-
-- ✅ Safe: run freely.
-- ⚠️ Confirm: summarize for the user and wait for OK.
-- 🔴 Destructive: full summary, then an explicit yes from the user.
-
-Full syntax: `fui <command> --help`. The fui skill (`fui skill`) has the Fui MCP tool → command map.
-
-## Commands
-
-| Command                                                                                     | R/M   | Risk |
-| ------------------------------------------------------------------------------------------- | ----- | ---- |
-| `use`, `use --clear`, `resolve`                                                             | M / R | ✅   |
-| `project list`                                                                              | R     | ✅   |
-| `project sync`                                                                              | M     | ✅   |
-| `project new`, `project update`, `project publish-config`                                   | M     | ⚠️   |
-| `user search`, `user list`                                                                  | R     | ✅   |
-| `user add`, `user set`                                                                      | M     | ⚠️   |
-| `user remove`                                                                               | M     | 🔴   |
-| `module list`, `module validate`, `module outline`, `module simulate`, `module preview`     | R     | ✅   |
-| `module get`, `module get-ui`, `module get-html`                                            | M     | ✅   |
-| `module new`, `module update`                                                               | M     | ⚠️   |
-| `module publish json`, `module publish html`, `module publish script`, `module publish css` | M     | ⚠️   |
-| `module delete`                                                                             | M     | 🔴   |
-| `component get`, `component list`                                                           | M     | ✅   |
-| `component preview`                                                                         | R     | ✅   |
-| `component new`, `component update`                                                         | M     | ⚠️   |
-| `component delete`                                                                          | M     | 🔴   |
-| `import list`, `import get`                                                                 | R     | ✅   |
-| `import new`, `import update`, `import upload`                                              | M     | ⚠️   |
-| `import delete`                                                                             | M     | 🔴   |
-| `db list`, `db alias list`                                                                  | R     | ✅   |
-| `db add`, `db add-by-name`, `db user-token`                                                 | M     | ✅   |
-| `db alias new`, `db token-rebuild`                                                          | M     | ⚠️   |
-| `schema`, `sp list`, `sp help`, `sp verify`                                                 | R     | ✅   |
-| `schema pull`, `sp get`                                                                     | M     | ✅   |
-| `query`                                                                                     | R/M   | ⚠️   |
-| `sp save`, `sp rename`                                                                      | M     | ⚠️   |
-| `exec`                                                                                      | R/M   | 🔴   |
-| `sp deploy`, `sp delete`                                                                    | M     | 🔴   |
-| `right system list`, `right function list`                                                  | R     | ✅   |
-| `right system new/update`, `right function new/update`                                      | M     | ⚠️   |
-| `right system delete`, `right function delete`                                              | M     | 🔴   |
-| `skill get`, `skill ref`, `design list`, `design read`, `library`, `log read`               | R     | ✅   |
-| `skill sync`, `log clear`                                                                   | M     | ✅   |
-
-## Refresh scope
-
-Each refresh overwrites every file in its scope without asking (old copies go to `_history/`):
-
-| Files                                                                                                               | Refreshed by                                       |
-| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `module.json`, `header.html`, `body.html`, `script.js`, `_moduleInfo.json`, module-scope `uc-*.vue`, module imports | `fui module get`                                   |
-| project-scope `uc-*.vue` (`{projectId}/components/`)                                                                | `fui component get`, or `fui project sync` for all |
-| `project.json`, `_projectInfo.json`, `_modules.json`, `imports/*`                                                   | `fui project sync`                                 |
-| `_db/{alias}/schema.json` and all `_db/{alias}/*.sql` of one connection                                             | `fui schema pull`                                  |
-
-## Publish: which command for which file
-
-- Before publishing module.json: `fui module validate`, fix every error. For complex runtime logic (action chains, watch cascades, dialog flows) also `fui module simulate` the main flow.
-- Only `module.json` → `fui module publish json` (no preview needed).
-- `header.html` / `body.html` / title (with or without module.json) → `fui module preview`, user approves, then `fui module publish html --approval <token>`. It pushes module.json too.
-- `script.js` (also to clear it) → `fui module publish script`. `module publish json` does not push it.
-- `style.css` (also to clear it) → `fui module publish css`.
-- `uc-*.vue` → `fui component new <name>` the first time, `fui component update <name>` after; scope comes from `-m`; `<style scoped>` is sent as ComCSS.
-- Several files changed → one command per file, in turn. `fui file push <path...>` routes each path to its publisher; `fui file status` lists what is still unpublished (a local ledger; it never blocks a publish).
-
-## Database rules (enforced in code)
-
-- `query` / `exec`: summarize what the SQL does and what data it touches, and wait for the user. Writes (INSERT, UPDATE…SET, DELETE, MERGE, TRUNCATE, ALTER COLUMN) exit 3 until `--confirm-write`, added only after the user approved that exact write.
-- Always blocked, no flag unlocks them: `DROP TABLE`, `ALTER TABLE … DROP COLUMN`/`SWITCH`, `DELETE`/`UPDATE` without `WHERE` in `exec`. Show the SQL for the user to run by hand. `ALTER TABLE … ADD` and `DROP CONSTRAINT` are free.
-- Never call a live API SP or run sub-queries "to test" it: read its body (`fui sp get`) and reason, or `fui sp verify <name|Fn>` (reads the definition; `--check-grant` also reads permissions).
-- `apiMocks` for an SP that exists must come from `fui sp verify`, never guessed.
-- `fui sp deploy`: archives the live body to `_history/`, fixes CREATE/ALTER, grants EXECUTE to `[public]` on new procedures, clears the tAPI cache once. After an `ALTER PROCEDURE` through `exec`, run `fui sp help <name>` to clear the cache yourself, or tAPI keeps the old signature.
-- Never write `GRANT` into the `.sql` file: tAPI sends one batch without `GO`, so it would become part of the procedure body.
-- `fui db add` stores the connection in `{projectId}/_db/_connections.json` under the alias; if the project is unclear, ask the user.
-- Secrets only via stdin (`-`) or `--*-env VAR`; never print `_db/_connections.json` or `_db/config.json`.
-
-## Concurrency
-
-- Read-only commands can run in parallel.
-- Never in parallel: any 🔴 command, `module publish html` with anything else, two `sp deploy`.