@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/fui/references/team-run.md

@@ -0,0 +1,141 @@
+# Team run — plan, build, test, fix, then one approval
+
+The `fui` skill sends you here when a request is big enough for a team (see its "Choose how to work"). The user wants to stop supervising every step, testing by hand and describing bugs back to you. In a team run they answer your questions **once at the start** and approve the release **once at the end**. Everything between is yours: a builder builds, a tester who has not seen the builder's reasoning checks the result, and the builder fixes what the tester found.
+
+You are the **planner**. You do not write the module or the stored procedures yourself, even when it looks quicker: your judgment is what decides whether the work is done, and it stays independent only if the work is not yours.
+
+## Before the first run
+
+- The two sub-agents are `fui-builder` and `fui-tester`; fui installs them for Claude Code with its skill, and a session started before that does not see them. If your agent list does not have them, do not stop: follow "Without sub-agents" at the end, and say in the review packet that a new session gives the next run an independent tester.
+- The rules of the `fui` skill apply to you and to both agents. If you have not read `references/INDEX.md` this session, run `fui skill ref references/INDEX.md` first.
+- One module per run, with the stored procedures it calls. For a system of several modules, plan the modules with [system-design.md](system-design.md), then run them one at a time.
+- Use the `fui` CLI only. If FUI MCP tools are also connected to this session, do not call them: the approval rules cover `fui` commands, not MCP tools.
+
+## The run
+
+Pick a run id `YYYYMMDD-HHMM-<short-name>` and keep everything about the run in `{workspace}/_team/<runId>/`.
+
+### 1. Plan
+
+1. Read what exists: `fui module get` (it overwrites local files, so do it now, before anyone edits), `fui module outline`, `fui schema --search`, `fui sp get` for procedures the task touches, and one or two similar modules of the project for its conventions.
+2. Collect everything only the user can decide and **ask it in one message**: what the feature must do where the request is ambiguous; plain `module.json` or a `uc-*.vue` component (approach A or B in [fullstack-workflow.md](fullstack-workflow.md) §Step 1b); App-mode or Web-mode when unclear; which connection (`--db`) when the project has several. Propose an answer to each so the user can reply "ok".
+3. A new module needs its record first: `fui module new`, then `fui module get`. This asks the user for approval; it is part of the start.
+4. Write `_team/<runId>/plan.md` from the template below. The acceptance criteria are the heart of it: the tester checks them and nothing else, so each must be something a command or a screenshot can show to be true or false.
+
+### 2. Build
+
+Start `fui-builder` with: the path of `plan.md`, the project and module ids, and the connection. Nothing more; the plan must stand on its own.
+
+Wait until it has finished before doing anything else. Run it in the foreground when the Agent tool lets you choose; otherwise wait for its completion notice. Its last message is a hand-off: files changed, what it checked and how, open doubts, and any question it could not answer from the plan. Answer a question yourself when the plan or the user's answers settle it; otherwise ask the user, then continue the same builder.
+
+### 3. Test
+
+1. Before the tester starts, record the state of the work: `fui file status`, and a listing with sizes and modification times of the module folder and of the `.sql` files the plan names.
+2. Start a **new** `fui-tester` with only the path of `plan.md`, the ids and the connection. Do not pass the builder's hand-off, its mocks or your own opinion of the work: a tester told what to expect finds less.
+3. When it has finished, read `_team/<runId>/test-<round>.md`, then record the same state again. A module or `.sql` file that changed during the test means the tester edited the work: tell the user, and do not trust that round.
+
+### 4. Fix
+
+If the report lists defects, send the same builder (by its id or name, so it keeps its context) the path of the report and ask it to fix every defect and say what it changed for each. A continued agent runs in the background: wait for its completion notice. Then go back to step 3 with a new tester.
+
+Stop the loop when the tester reports no defect, after **three** fix rounds, or when the same criterion fails twice with no visible change. In the last two cases the run has not succeeded: go to step 5 and say so.
+
+A builder that keeps failing the same way usually means the plan is wrong, not the code. Re-read the criterion before sending it back a third time.
+
+### 5. Review packet
+
+Write `_team/<runId>/release.md` and show it to the user:
+
+- each acceptance criterion: passed or failed, with the evidence the tester gave (command, report line, screenshot path);
+- files changed and still unpublished (`fui file status`), and what the server will receive (`fui module preview`: its change list, including any `deleted component` line, and its approval token);
+- tables or columns to create, procedures to deploy, with the connection;
+- warnings the tester left open, in its words;
+- the release command (next section).
+
+Report a failed run as failed. A packet that hides an open defect costs the user more than the defect.
+
+### 6. Release
+
+After the user has read the packet, run the release as **one** command, steps joined with `&&` so it stops at the first failure, in this order:
+
+1. table changes (`fui exec -f <file> --db <connection>`), only those the plan lists;
+2. `fui sp deploy <name> --db <connection>` for each procedure;
+3. project-level files the module depends on (`fui component new|update <name> -p <project>` with no `-m`, `fui project publish-config`);
+4. the module: `fui module publish html --approval <token>` when header, body or title changed, otherwise `fui file push <changed files...>`.
+
+Show the packet and this command in one message and ask the user to approve it. That is the one approval of the run: run the command only after a clear yes, and do not ask again step by step. Builder and tester cannot run any of these commands; you are the only one who releases.
+
+Then report what each step printed. If a step failed, say which, what ran before it, and what is now on the server. A deploy that fails on a SQL error is a defect: send it to the builder (step 4), and release again with only the steps that did not run.
+
+Finish with `fui file status`: nothing of this module should be left unpublished.
+
+## Rules that keep the run honest
+
+- **Nothing reaches the server before the release.** No publish, deploy, `fui exec`, `--confirm-write` or delete during plan, build, test or fix. The agents are blocked from these, and you run them only with the user's yes.
+- **One exception, asked for separately.** A module cannot be rendered while a project-level `uc-*.vue` or `project.json` differs from the server (`--render` hard-blocks). If the task changes one, the builder checks it alone with `fui component preview`, then you ask the user to approve publishing just that file so the module can be rendered. Say this in the plan so the user expects it.
+- **Stored procedures are never run to test them.** The builder and the tester read the body and reason about it (`fui sp verify`); the UI is tested on mock data shaped by that body. A SQL syntax error therefore first shows at deploy. Tell the user this limit in the packet when the run adds or changes procedures.
+- **Never sync in the middle.** `fui module get`, `fui project sync` and `fui schema pull` replace local files with the server copy. After step 1 nobody runs them until the release is done.
+- **Agents work one at a time.** Never start the tester while the builder is running, and never two builders on one module.
+
+## plan.md
+
+```markdown
+# <run id>: <one line goal>
+
+Project / module: <projectId> / <moduleId> (new or existing)
+Connection: <project/connectionName>, apiName <apiName>
+Approach: A (module.json) or B (uc-*.vue): <why>
+Design mode: App or Web
+
+## What the user asked
+
+<the request in their words, then the answers they gave to your questions>
+
+## Scope
+
+In: <screens, actions, procedures, tables>
+Out: <what this run must not touch>
+
+## Data contract
+
+For each API the module calls:
+
+- spAPI_<Name> (new | changed | existing): params <@a type, ...> → columns <A, B, ...>; errors <when it must RAISERROR>
+
+## Acceptance criteria
+
+- AC1 <observable fact>. Check: <assert on vueData | what the screenshot must show | what the procedure body must contain>
+- AC2 ...
+
+## Needs the user during the run
+
+<"nothing", or the project-level file that must be published before rendering>
+```
+
+Write criteria about behavior and data, not about wording in `module.json`: "after Save with an empty name the dialog stays open and shows the server message" can be checked; "uses f-table" cannot fail usefully. Cover the empty list, the server error and the permission-limited user wherever the feature has them.
+
+## release.md
+
+```markdown
+# <run id>: <passed | NOT passed>
+
+| Criterion | Result | Evidence                   |
+| --------- | ------ | -------------------------- |
+| AC1 ...   | pass   | test-2.md, render-full.png |
+
+Fix rounds: <n>
+Open defects and warnings: <none, or the list>
+Not verified: <e.g. SQL syntax of new procedures, seen only at deploy>
+
+## What will change on the server
+
+<module files, components created/updated/deleted, procedures, tables>
+
+## Release command
+
+<the single command>
+```
+
+## Without sub-agents
+
+On an agent that cannot start sub-agents, or when `fui-builder` and `fui-tester` are not installed, do the same steps yourself, in the same order, with the same files. For step 3, close the build first: write the hand-off, then re-read `plan.md` and test from the criteria as if someone else had built it, writing your own mocks from `fui sp verify`.

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

@@ -0,0 +1,211 @@
+# fui commands — safety registry
+
+> Owns: **risk class of every command, "which command for which file" publish rules, what users say → command, DB guards enforced in code, the error-log loop**. DB/SP procedure: [db-workflow.md](db-workflow.md); definition of done: [verification.md](verification.md). Flags: `fui <command> --help` (`fui <group> --help` lists a group, e.g. `fui right --help`).
+
+Two axes per command:
+
+- `R` reads only (touches no byte on disk) / `M` writes the server **or the local workspace**. A command that "only fetches" still **overwrites local files**, which is how unpublished edits get lost; 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.
+
+**Default:** a command is mutating and needs confirmation unless this file marks it `R` / ✅. **Per call:** judge the actual input; the same command can be safe or not.
+
+**Strict mode (`FUI_STRICT=1`)**, for runs nobody reviews step by step: `module publish json|html|script|css`, `component new|update`, `project publish-config` and `sp deploy` are **blocked** until the skill was loaded this session (`fui skill get` / `fui skill ref`), and validator **errors block** publishing module.json. Without it both are warnings.
+
+## Sync before reading
+
+Every file fetched from the server (`module.json`, `header.html`, `body.html`, `script.js`, `_moduleInfo.json`, `uc-*.vue`, `project.json`, `_db/{connectionName}/*.sql`…) is a copy from the last checkout; someone may have changed the server since.
+
+**Older than 48 hours → refresh before reading or editing**, so you never review a stale copy or publish over newer work. `module validate`, `outline`, `simulate`, `preview`, `schema` and `sp verify` print `warning: ... last synced N days ago ... run: <command>`: run that command first.
+
+Each refresh rewrites **every** file in its scope, never one file:
+
+| Files                                                                                                                             | Refreshed by                                       |
+| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `module.json`, `header.html`, `body.html`, `script.js`, `_moduleInfo.json`, module-scope `uc-*.vue`, import contents (both scopes) | `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/*` (contents too)                                                  | `fui project sync`                                 |
+| `_db/{connectionName}/schema.json` and all its `*.sql`, **one connection per call**                                               | `fui schema pull`                                  |
+| one SP                                                                                                                            | `fui sp get`                                       |
+
+**It always overwrites and never asks.** What protects local edits is `{workspace}/_history/`: each file about to be overwritten or deleted is copied there first, same path shape, timestamp in the name:
+
+```
+_history/{projectId}/modules/{moduleId}/module_20260801_143022.json
+_history/{projectId}/_db/{connectionName}/spAPI_X_20260801_143022.sql
+_history/{projectId}/components/uc-abc_20260801_143022_deleted.vue     ← deleted, not overwritten
+```
+
+`archived N local file(s) that differed from the server` is a notice, not a question. Bring a copy back with `fui file restore <path>` (`fui file history <path>` lists versions), then publish or deploy as usual. `_history` is never cleaned up automatically.
+
+## What users say → command
+
+Users name commands loosely, often in Vietnamese.
+
+| User says                                                                                              | Command                                                                 |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| "which module is active" / "đang làm module gì"                                                        | `fui use`                                                               |
+| "switch module" / "chọn module", a pasted module URL or `/project/module` route, or just a module name | `fui use <target>`                                                      |
+| "list projects" / "danh sách project"                                                                  | `fui project list`                                                      |
+| "new project from scratch" / "tạo dự án mới", "tạo DB + project FUI mới"                               | [project-provisioning.md](project-provisioning.md), 6 steps; do not start with `fui project new` |
+| "new database", "register an alias" / "đăng ký alias", "thêm DB vào tAPI"                              | `fui db alias new`                                                      |
+| "let someone edit this project" / "cấp quyền admin project", "thêm người vào project"                  | `fui user search` → `fui user add`                                      |
+| "who can edit this project" / "ai được sửa project này"                                                | `fui user list`                                                         |
+| "update project.json", "edit the project menu" / "sửa menu project"                                    | edit `{projectId}/project.json`, then `fui project publish-config`      |
+| "connect the DB but I only know the alias" / "không có dbToken"                                        | `fui db alias list` → `fui db add-by-name`                              |
+| "sync / refresh the project" / "đồng bộ project", "lấy project.json"                                   | `fui project sync`                                                      |
+| "get / pull / clone / refresh the module" / "lấy module về", "pull mới nhất"                           | `fui module get`                                                        |
+| "new module" / "tạo module mới"                                                                        | `fui module new`                                                        |
+| "rename the module", "change its ID / framework" / "đổi tên module"                                    | `fui module update`                                                     |
+| "delete the module" / "xóa module"                                                                     | `fui module delete`                                                     |
+| "preview", "diff before upload" / "xem trước", "kiểm tra trước khi up"                                 | `fui module preview`                                                    |
+| "validate" / "kiểm tra module.json"                                                                    | `fui module validate`                                                   |
+| "review the layout", "outline" / "review giao diện", "xem layout"                                      | `fui module outline`                                                    |
+| "simulate", "test the flow" / "mô phỏng", "chạy thử action"                                            | `fui module simulate`                                                   |
+| "render the UI", "screenshot", "check on mobile" / "render giao diện", "xem trên mobile"               | `fui module simulate --render`                                          |
+| "push module.json" / "cập nhật module.json"                                                            | `fui module publish json`                                               |
+| "push header / body / html" / "up header", "up body", "đẩy lên"                                        | `fui module preview` → `fui module publish html`                        |
+| "push script" / "up script", "cập nhật script"                                                         | `fui module publish script`                                             |
+| "push style / CSS" / "up style", "cập nhật CSS module"                                                 | `fui module publish css`                                                |
+| "test the component alone" / "thử component", "component trên mobile"                                  | `fui component preview`                                                 |
+| "new component" / "tạo component"                                                                      | `fui component new`                                                     |
+| "push the component" / "up component", "sửa component"                                                 | `fui component update`                                                  |
+| "sync components" / "sync component"                                                                   | `fui component list`                                                    |
+| "list / sync import files" / "danh sách import file"                                                   | `fui import list`                                                       |
+| "new SP", "deploy the SP" / "tạo SP mới", "cập nhật SP"                                                | `fui sp save` → `fui sp deploy`                                         |
+| "add a function right" / "thêm quyền chức năng", "tạo FunctionRight"                                   | `fui right function new`                                                |
+| "save the user token" / "lưu user token", "token để gọi API"                                           | `fui db user-token`                                                     |
+| "DB password changed" / "đổi password DB", "rebuild dbToken"                                           | `fui db token-rebuild`                                                  |
+| "which DBs does this project use" / "project này đang nối những DB nào"                                | `fui db list`                                                           |
+| "connect one more database" / "nối thêm một database nữa"                                              | `fui db add` again with the new apiName                                 |
+| **"sync the db", "refresh schema"** / **"đồng bộ db", "cập nhật schema", "làm mới schema"**            | `fui schema pull`, **never `fui project sync`**. No connection yet → ask for the connection details; do not run something else instead |
+| "list designs" / "có style nào" · "use style X" / "dùng style X"                                       | `fui design list` · `fui design read <brand>`                           |
+
+## Commands
+
+### Session, project, users
+
+| Command                                   | R/M | Risk | Notes |
+| ----------------------------------------- | --- | ---- | ----- |
+| `use`, `resolve`, `file where`            | R   | ✅   | read the target and how it resolved |
+| `use <target>`, `use --clear`             | M   | ✅   | session target only; no data changes |
+| `project list`                            | R   | ✅   | |
+| `project sync`                            | M   | ✅   | refreshes every project-level file and import content; removes local `.vue`/import files that were tracked and are gone on the server (unpublished new ones are kept) |
+| `project new`                             | M   | ⚠️   | needs `SystemRight >= 3` on `fp`; the server reads **6 fields only** (`ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `Router`). `title`/`login`/`apiDomain`/`menu` are ignored silently: runtime config goes through `project publish-config`. Full procedure: [project-provisioning.md](project-provisioning.md) |
+| `project update`                          | M   | ⚠️   | edits an existing project; `projectData.id` is required (without it the server would create) |
+| `project publish-config`                  | M   | ⚠️   | pushes the local **file** `{projectId}/project.json`; edit the file first. A JSON syntax error is a hard stop (pushing `{}` would wipe menu and settings). Skips when unchanged |
+| `user search`, `user list`                | R   | ✅   | `user search` is the only source of the exact `UserID`: show its rows and let the user pick. `user list` = who may edit the project in the FUI IDE (`UserRight` 1/2/3), **not** the `acc` `SystemRight` ([permission-system.md](permission-system.md)) |
+| `user add`, `user set`                    | M   | ⚠️   | `add` only for a user with no right, `set` only for one who has it; each hard-errors in the other case. Levels: 1 view · 2 develop · 3 admin |
+| `user remove`                             | M   | 🔴   | revokes the right; summarize and wait for a yes |
+
+### Modules
+
+| Command                                                 | R/M | Risk | Notes |
+| ------------------------------------------------------- | --- | ---- | ----- |
+| `module list`                                           | R   | ✅   | also refreshes the local module cache (`_modules.json`) |
+| `module get`                                            | M   | ✅   | rewrites the whole module locally and sets the target; differing local files go to `_history/`; `.vue`/import files the server dropped are removed (`_deleted` copy kept) |
+| `module get-ui`, `module get-html`                      | M   | ✅   | overwrite local `module.json` / `body.html` when the module is checked out. Not read-only |
+| `module new`                                            | M   | ⚠️   | creates an **empty** module on the server; confirm id and name first, then `fui module get`. An id already in `_modules.json` is a hard error |
+| `module update`                                         | M   | ⚠️   | metadata of an existing module. Changing `ModuleID` changes its URL (old links break) and renames the local folder: warn the user |
+| `module delete`                                         | M   | 🔴   | **permanent on the server, no history there**; archives the local folder and clears a matching session target |
+| `module validate`, `module outline`, `module preview`   | R   | ✅   | `validate` does **not** read `script.js`: an `EXE`/`FUN` calling an unwritten function only shows in `--render` as `... is not defined` ([advanced-techniques.md](advanced-techniques.md) §2). `[design]` warnings must be fixed unless the user asked for that style |
+| `module simulate`, `module check`, `component preview`  | R   | ✅   | write only `_preview/`, `_componentPreview/` and `_testdata/`; an unmocked read-only API may be called for real ([verification.md](verification.md)) |
+| `module publish json`                                   | M   | ⚠️   | **only** module.json; no preview needed |
+| `module publish script`, `module publish css`           | M   | ⚠️   | an **empty** file clears it on the server; a missing file is refused |
+| `module publish html`                                   | M   | ⚠️   | header/body/title **and** module.json; needs the token from `module preview`, which covers the whole payload (any file edited after the preview voids it). Also pushes non-empty `script.js`/`style.css`, and **reconciles `components/*.vue` with the server: a server component with no local file is DELETED** (the preview lists it as `deleted component <name>`) |
+
+### Components
+
+| Command             | R/M | Risk | Notes |
+| ------------------- | --- | ---- | ----- |
+| `component get`     | M   | ✅   | prints the source and overwrites the local `.vue` (old copy to `_history/`) |
+| `component list`    | M   | ✅   | refreshes `_components.json`; removes tracked `.vue` files the server dropped |
+| `component preview` | R   | ✅   | one local `.vue` alone in a real browser; works before it is pushed ([component-design.md](component-design.md)) |
+| `component new`     | M   | ⚠️   | first push. Refreshes `_components.json` from the server **first**; a name that exists is a hard error (a blind insert makes two records with one name) |
+| `component update`  | M   | ⚠️   | later pushes; hard-errors when the component is not on the server, never creates. Sends `<style scoped>` as `ComCSS` |
+| `component delete`  | M   | 🔴   | **permanent on the server**; archives the local `.vue` |
+
+Scope, for every component command:
+
+| Given                                              | Scope                             |
+| -------------------------------------------------- | --------------------------------- |
+| `-p P -m M`                                        | module `M`                        |
+| `-p P` only                                        | project (global, loaded everywhere) |
+| nothing, inside a module folder or a module target | that module                       |
+| nothing, inside a project folder only              | project (global)                  |
+
+### Imports
+
+| Command                       | R/M | Risk | Notes |
+| ----------------------------- | --- | ---- | ----- |
+| `import list`                 | R   | ✅   | with `-p` it also syncs local `_imports.json` (metadata only) and removes orphaned content files |
+| `import get`                  | R   | ✅   | prints one file and writes it to every local `imports/` that declares it |
+| `import new`, `import update` | M   | ⚠️   | sort below the scope floor is raised: project ≥ 20, module ≥ 50 (framework uses ~1–10). `update` edits metadata, not the source |
+| `import upload`               | M   | ⚠️   | overwrites the source on the server and the local copies |
+| `import delete`               | M   | 🔴   | **permanent**; cleans the local copies |
+
+### Database and rights
+
+| Command                                    | R/M | Risk | Notes |
+| ------------------------------------------ | --- | ---- | ----- |
+| `db list`, `db test`, `token decode`       | R   | ✅   | never print secrets |
+| `db alias list`                            | R   | ✅   | databases your token may manage on `acc`; run it when an alias is unknown or `db add-by-name` finds nothing |
+| `db add`, `db add-by-name`                 | M   | ✅   | test, save, fetch the schema. `add-by-name` borrows a SQL login from a connection on the same `apiDomain`; "not found" means the alias does not exist **or** you may not manage it |
+| `db user-token`, `db default`, `db migrate` | M  | ✅   | local only |
+| `db token-rebuild`                         | M   | ⚠️   | overwrites the stored token; `--db` is required when the project has several connections |
+| `db alias new`                             | M   | ⚠️   | registers an existing database as a tAPI alias on `acc`; the login must be the **application** account (execute-only), never a `db_owner` dev login. Ask the user first |
+| `schema`, `sp list`, `sp path`, `sp help`, `sp verify` | R | ✅ | `schema` reads one connection: a "missing" table usually means the wrong connection. `sp list` covers every connection unless `--db`. `sp help` also clears the tAPI cache for that function |
+| `schema pull`                              | M   | ✅   | rewrites `_db/{connectionName}/` of **one** connection, bodies included. Files of procedures dropped on the server are archived. Files in neither schema are only **listed** (maybe an undeployed draft): read that note and ask before `--prune-local-only` |
+| `sp get`                                   | M   | ✅   | overwrites `_db/{connectionName}/{name}.sql` (old copy to `_history/`). Not read-only |
+| `sp save`                                  | M   | ⚠️   | local only. There is no "create SP" command: a new SP is `sp save` → `sp deploy`; with several connections name `--db` on the first save |
+| `sp rename`                                | M   | ⚠️   | renames on the server and the local file; summarize first |
+| `query`                                    | R/M | ⚠️   | reads and, on the user's request, writes real data. Default cap 200 rows; `TOP 20` to look at structure; no `varbinary(max)`/large `nvarchar(max)` columns |
+| `exec`                                     | R/M | 🔴   | DDL/DML. A `CREATE`/`ALTER PROCEDURE` here gets **no auto-grant and no cache clear**; the output names the command to run next |
+| `sp deploy`, `sp delete`                   | M   | 🔴   | `deploy` saves the live definition to `_history/` (the rollback copy), fixes CREATE/ALTER, grants, clears the tAPI cache; summarize the SP and wait. `delete` is permanent |
+| `right system list`, `right function list` | R   | ✅   | read `acc` and refresh `{projectId}/_db/rights.json`; **until they ran once, validate/simulate/render cannot check right codes** |
+| `right system new/update`, `right function new/update` | M | ⚠️ | create and edit are separate; `update` needs the id from `list` |
+| `right system delete`, `right function delete` | M | 🔴 | `function delete` also removes every user assignment of that code |
+
+Guarding with a right code that is not defined fails silently: `rightTest()` is always false, the control vanishes with no JS error, and **the preview still shows it** ([permission-system.md](permission-system.md)).
+
+### Skill, workspace files, maintenance
+
+| Command                                                         | R/M | Risk | Notes |
+| --------------------------------------------------------------- | --- | ---- | ----- |
+| `skill get`, `skill ref`, `design list`, `design read`, `library` | R | ✅   | `skill get` prints SKILL.md + the router; Tier A files come from `skill ref` |
+| `remote module`, `remote project`, `remote diff`                | R   | ✅   | server copy, no local writes |
+| `file status`, `file history`, `file ledger`                    | R   | ✅   | `file ledger --mark` only records a file as published; it pushes nothing |
+| `file restore`                                                  | M   | ✅   | local only; the current file is archived first |
+| `file push`                                                     | M   | ⚠️   | routes each path to its publisher above; the same rules apply |
+| `log read`                                                      | R   | ✅   | failures grouped by command and error signature, most frequent first |
+| `log clear`                                                     | M   | ✅   | after the patterns were folded into the skill |
+
+**Error-log loop.** Every failed command is appended to `{workspace}/_logs/tool-errors.jsonl`, except a block that only waits for `--confirm-write`. A group that keeps repeating in `fui log read` is a gap in these references: fix the reference, then `fui log clear`. The `guards that blocked by design` list at the end (DROP TABLE, data-losing ALTER TABLE, DELETE/UPDATE without WHERE) is not a gap.
+
+## Publish: which command for which file
+
+- Before publishing module.json: `fui module validate`, fix every error, then `fui module outline` (row widths, dialogs nobody opens, actions nobody calls). For complex runtime logic (action chains, watch cascades, dialog flows) also `fui module simulate` the main flow with asserts.
+- Only `module.json` → `fui module publish json` (no preview needed).
+- `header.html` / `body.html` / title (with or without module.json) → `fui module preview`, the user reads the diff and approves, then `fui module publish html --approval <token>`. It pushes module.json too. Never run it without the user's approval.
+- `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. A **project-scope** component must be previewed and pushed **before** rendering a module that uses it: `--render` hard-blocks when the local file differs from the server.
+- Several files changed → one command per file, in turn. `fui file push <path...>` routes each path to its publisher.
+
+**Backstop, not a substitute.** Each module keeps a local ledger of content hashes from the last publish/sync. Forgot a file → `module validate` and the publish commands print `unpublished local files: ...`, and `fui file status` lists each with its command. It never blocks a publish. The same ledger skips duplicates: `module publish json|script|css` and `component update` print `skip <file> unchanged since the last publish/sync` and make no request. `module publish html` always pushes.
+
+## Database rules (enforced in code)
+
+- `query` / `exec`: say what the SQL does and what data it touches, and wait for the user. Writes (INSERT, UPDATE…SET, DELETE, MERGE, TRUNCATE, `SELECT … INTO` a real table, a write inside `EXEC('…')` or `sp_executesql`, `DROP PROCEDURE`/`FUNCTION`/`VIEW`, ALTER COLUMN) exit 3 until `--confirm-write`, added only after the user approved that exact write. It is a confirmation gate, not an obstacle to work around.
+- Table DDL is judged by data loss, **per statement**: free `ALTER TABLE … ADD` and `DROP CONSTRAINT` · `--confirm-write` for `ALTER COLUMN` (narrowing numeric or date precision loses data silently) · always blocked `DROP TABLE`, `DROP DATABASE`, `DROP COLUMN`, `SWITCH`, `xp_cmdshell` and any action fui cannot parse. A blocked statement wins over a confirmable one. `DELETE`/`UPDATE` without `WHERE` is blocked too, in `query` and `exec` (a `MERGE` is scoped by its `ON`). A `--` or a quote inside a `[name]` or `"name"` does not hide the statements after it. Show blocked SQL for the user to run by hand; no flag unlocks it.
+- 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>`. `sp verify` calls no endpoint; its only network reads are metadata (`OBJECT_DEFINITION` when no local `.sql`, permissions with `--check-grant`). An unreadable body is a hard error: it never guesses from the name.
+- `--mocks` for an SP that **exists** must be the snippet `fui sp verify` prints, never a guessed shape. On `🚨 UNVERIFIED MOCK SHAPE` stop, run `fui sp verify`, copy the snippet. Invented data is right only for an SP that does not exist yet.
+- `fui sp deploy` asks the server whether the object exists, so `CREATE PROCEDURE` for an existing SP is fine: do not edit the file to `ALTER` and redeploy. tAPI parameters with a default value are hard-blocked.
+- After an `ALTER PROCEDURE` through `exec`, run `fui sp help <name>` once to clear the tAPI cache, or tAPI keeps serving 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. `sp deploy` grants new procedures and re-checks; on `lacks EXECUTE` run the printed command, **do not redeploy**.
+- A project can use several databases. `fui db add` stores each in `{projectId}/_db/_connections.json` under a `connectionName` (its `_db/` folder); `apiName` is a separate field, only the route alias, and may repeat across zones. `--db` takes a connectionName (a unique apiName also works); when ambiguous, commands print a menu: pick a line, never guess. Project unclear → ask the user.
+- Secrets only via stdin (`-`) or `--*-env VAR`; never print `_db/_connections.json`.
+
+## Concurrency
+
+- Read-only commands can run in parallel.
+- Never in parallel: any 🔴 command, `module publish html` with anything else, two `sp deploy`.