@josephyan/qingflow-app-user-mcp 1.1.25 → 1.1.27

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.1.25
+npm install @josephyan/qingflow-app-user-mcp@1.1.27
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.1.25 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.1.27 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -23,19 +23,17 @@ This package bootstraps a local Python runtime on first install and then starts
 Bundled skills:
 
 - `skills/qingflow-app-user`
-- `skills/qingflow-mcp-setup`
 - `skills/qingflow-record-insert`
 - `skills/qingflow-record-update`
 - `skills/qingflow-record-delete`
 - `skills/qingflow-record-import`
 - `skills/qingflow-task-ops`
 - `skills/qingflow-record-analysis`
+- `skills/qingflow-mcp-setup`
 
 Note:
 
 - The skill files are included in the npm package.
-- Installing the npm package does not overwrite agent skills automatically.
-- To mount bundled skills from an installed package, run `qingflow-app-user-mcp-skills install --agent codex --scope user`.
-- For one-shot `npx -p` installs, prefer `--copy` because symlinks would point into the npm execution cache.
-- Use `qingflow-app-user-mcp-skills list` to inspect bundled skills. The installer defaults to symlinks for stable package installs and refuses to overwrite existing skills unless `--force` is provided.
+- On install, the package installs bundled skills into `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset) by symlink and refreshes them on package updates.
+- You can also run `qingflow-app-user-mcp skills list` or `qingflow-app-user-mcp skills install --agent codex|claude-code|cursor|generic --scope user|project [--copy] [--force]`.
 - If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.

package/docs/local-agent-install.md

@@ -101,51 +101,7 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露对应入口：CLI 包暴露 `qingflow` / `qingflow-skills`；app-user 包暴露 `qingflow-app-user-mcp` / `qingflow-app-user-mcp-skills`；app-builder 包暴露 `qingflow-app-builder-mcp` / `qingflow-app-builder-mcp-skills`
-5. 携带 `skills/<skill-name>/SKILL.md`，但不在 `postinstall` 阶段自动覆盖本机 agent skills
-
-## Skills 挂载
-
-显式查看包内 skills：
-
-```bash
-qingflow-skills list
-```
-
-独立 MCP split 包使用包专属 skills 命令，避免全局安装多个包时发生 bin 覆盖：
-
-```bash
-qingflow-app-user-mcp-skills list
-qingflow-app-builder-mcp-skills list
-```
-
-显式挂载到 Codex 用户目录：
-
-```bash
-qingflow-skills install --agent codex --scope user
-```
-
-如果通过一次性 `npx -p <package>` 执行安装，请加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
-
-```bash
-npx -y -p @qingflow-tech/qingflow-cli qingflow-skills install --agent codex --scope user --copy
-```
-
-也可以挂载到项目级 agent 目录：
-
-```bash
-qingflow-skills install --agent claude-code --scope project
-qingflow-skills install --agent cursor --scope project --copy
-qingflow-skills install --agent all --scope project
-```
-
-默认行为：
-
-- `--mode symlink`：使用 symlink，让 npm 包版本成为单一来源
-- `--scope user`：安装到用户级 agent skills 目录
-- `--agent codex`：目标 agent 为 Codex
-- 不覆盖已有同名 skill；需要替换时显式加 `--force`
-- 每次安装会在目标 skills 目录下写入 `.qingflow-skill-sources/<skill>.json`，记录 package、version、source、destination、agent、scope、mode
+4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
 
 ## 本地验证
 
@@ -154,31 +110,24 @@ qingflow-skills install --agent all --scope project
 ```bash
 cd qingflow-support/mcp-server
 node ./npm/bin/qingflow.mjs --help
-node ./npm/bin/qingflow-skills.mjs list
 node ./npm/bin/qingflow-app-user-mcp.mjs
 node ./npm/bin/qingflow-app-builder-mcp.mjs
 ```
 
-如果你是全局安装对应包：
+如果你是全局安装：
 
 ```bash
 qingflow --help
-qingflow-skills list
 qingflow-app-user-mcp
-qingflow-app-user-mcp-skills list
 qingflow-app-builder-mcp
-qingflow-app-builder-mcp-skills list
 ```
 
-如果你是把包安装到了某个本地 agent workspace，安装对应包后命令通常位于：
+如果你是把包安装到了某个本地 agent workspace，命令通常位于：
 
 ```bash
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow
-/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-skills
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
-/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp-skills
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
-/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp-skills
 ```
 
 如果你是从 tgz 安装到某个空目录，命令通常位于：
@@ -268,7 +217,7 @@ qingflow-app-builder-mcp-skills list
       "command": "npx",
       "args": [
         "-y",
-        "@qingflow-tech/qingflow-app-user-mcp"
+        "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -281,7 +230,7 @@ qingflow-app-builder-mcp-skills list
       "command": "npx",
       "args": [
         "-y",
-        "@qingflow-tech/qingflow-app-builder-mcp"
+        "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -323,7 +272,7 @@ npm install
 
 如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
 
-1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
+1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
 2. 删除安装目录下的 `.npm-python`
 3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
 4. 再启动 MCP 客户端

package/entry_point.py

@@ -7,7 +7,7 @@ src_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
 if src_path not in sys.path:
     sys.path.insert(0, src_path)
 
-from qingflow_mcp.server_app_user import main
+from qingflow_mcp.server import main
 
 if __name__ == "__main__":
     main()

package/npm/bin/qingflow-app-user-mcp.mjs

@@ -1,7 +1,38 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
 
-const packageRoot = getPackageRoot(import.meta.url);
+function resolvePackageModule(metaUrl, ...segments) {
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  // bin files live in <pkg>/npm/bin/, runtime.mjs lives in the sibling <pkg>/npm/lib/,
+  // so step up one level before joining the requested segments.
+  const direct = path.join(scriptDir, "..", ...segments);
+  if (fs.existsSync(direct)) {
+    return pathToFileURL(direct).href;
+  }
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
+    const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
+    if (fs.existsSync(fromBin)) {
+      return pathToFileURL(fromBin).href;
+    }
+  }
+  throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
+}
 
+const { getPackageRoot, spawnServer } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
+const packageRoot = getPackageRoot(import.meta.url);
 spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -5,6 +5,12 @@ import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
 
+const PKG_BY_BIN = {
+  qingflow: "qingflow-cli",
+  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
+  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
+};
+
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -28,7 +34,18 @@ function commandWorks(command, args) {
 }
 
 export function getPackageRoot(metaUrl) {
-  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
+  const scriptPath = fileURLToPath(metaUrl);
+  const scriptDir = path.dirname(scriptPath);
+  if (path.basename(scriptDir) === ".bin") {
+    const binName = path.basename(scriptPath);
+    const pkgName = PKG_BY_BIN[binName];
+    if (!pkgName) {
+      throw new Error(`Unknown qingflow command: ${binName}`);
+    }
+    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
+    return path.join(scriptDir, "..", scope, pkgName);
+  }
+  return path.resolve(scriptDir, "..", "..");
 }
 
 export function getCodexHome() {
@@ -137,6 +154,43 @@ function writeSkillProvenance(skillsDestRoot, skillName, payload) {
   fs.writeFileSync(path.join(provenanceRoot, `${skillName}.json`), `${JSON.stringify(payload, null, 2)}\n`);
 }
 
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withSkillInstallLock(skillsDestRoot, callback) {
+  const lockDir = path.join(skillsDestRoot, ".qingflow-skill-install.lock");
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > 300_000) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - startedAt > 30_000) {
+        throw new Error(`Timed out waiting for skill install lock: ${lockDir}`);
+      }
+      sleepMs(100);
+    }
+  }
+  try {
+    return callback();
+  } finally {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
 export function installBundledSkills(
   packageRoot,
   {
@@ -180,27 +234,29 @@ export function installBundledSkills(
     mode,
   };
 
-  for (const skillName of wanted) {
-    const src = path.join(skillsSrc, skillName);
-    const dest = path.join(skillsDestRoot, skillName);
-    const installResult = installOneSkill(src, dest, { force, mode });
-    result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
-    if (installResult.status !== "conflict") {
-      writeSkillProvenance(skillsDestRoot, skillName, {
-        package: packageJson.name ?? null,
-        version: packageJson.version ?? null,
-        skill: skillName,
-        source: src,
-        destination: dest,
-        agent,
-        scope,
-        mode,
-        installed_at: new Date().toISOString(),
-      });
+  return withSkillInstallLock(skillsDestRoot, () => {
+    for (const skillName of wanted) {
+      const src = path.join(skillsSrc, skillName);
+      const dest = path.join(skillsDestRoot, skillName);
+      const installResult = installOneSkill(src, dest, { force, mode });
+      result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
+      if (installResult.status !== "conflict") {
+        writeSkillProvenance(skillsDestRoot, skillName, {
+          package: packageJson.name ?? null,
+          version: packageJson.version ?? null,
+          skill: skillName,
+          source: src,
+          destination: dest,
+          agent,
+          scope,
+          mode,
+          installed_at: new Date().toISOString(),
+        });
+      }
     }
-  }
 
-  return result;
+    return result;
+  });
 }
 
 function parseSkillsCliArgs(args) {
@@ -480,6 +536,17 @@ function getVenvPip(packageRoot) {
     : path.join(getVenvDir(packageRoot), "bin", "pip");
 }
 
+function findOfflineProjectWheel(findLinksDir) {
+  const wheels = fs
+    .readdirSync(findLinksDir)
+    .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
+    .sort();
+  if (wheels.length === 0) {
+    throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
+  }
+  return path.join(findLinksDir, wheels[wheels.length - 1]);
+}
+
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -528,7 +595,20 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
+  const pipArgs = ["install", "--disable-pip-version-check"];
+  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
+    pipArgs.push("--no-index");
+  }
+  if (offlineFindLinks) {
+    pipArgs.push("--find-links", offlineFindLinks);
+  }
+  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
+    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
+  } else {
+    pipArgs.push(".");
+  }
+  runChecked(pip, pipArgs, { cwd: packageRoot });
 
   fs.writeFileSync(
     stampPath,

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,6 +6,15 @@ try {
   console.log("[qingflow-mcp] Bootstrapping Python runtime...");
   ensurePythonEnv(packageRoot, { commandName: "qingflow-app-user-mcp" });
   console.log("[qingflow-mcp] Python runtime is ready.");
+  const skills = installBundledSkills(packageRoot, { force: true });
+  if (!skills.skipped) {
+    const changed = [
+      skills.installed.length ? `installed=${skills.installed.join(",")}` : "",
+      skills.unchanged.length ? `unchanged=${skills.unchanged.join(",")}` : "",
+      skills.conflicts.length ? `conflicts=${skills.conflicts.join(",")}` : "",
+    ].filter(Boolean).join(" ");
+    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${changed || "none"}`);
+  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.1.25",
+  "version": "1.1.27",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "qingflow-app-user-mcp": "./npm/bin/qingflow-app-user-mcp.mjs",
-    "qingflow-app-user-mcp-skills": "./npm/bin/qingflow-skills.mjs"
+    "qingflow-app-user-mcp": "./npm/bin/qingflow-app-user-mcp.mjs"
   },
   "scripts": {
     "postinstall": "node ./npm/scripts/postinstall.mjs"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.25"
+version = "1.1.27"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -1,67 +1,66 @@
 ---
 name: qingflow-app-user
-description: Route Qingflow end-user requests to the right specialized operational skill using the current Wingent Momo runtime MCP session. Use when the task is operational but it is not yet clear whether it is record CRUD or final analysis.
+description: Route Qingflow end-user requests to the right specialized operational skill after the MCP is already connected and authenticated. Use when the task is operational but it is not yet clear whether it is record CRUD or final analysis.
 metadata:
   short-description: Router for Qingflow operational skills
 ---
 
 # Qingflow App User
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.30.1`
 
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.
-In Wingent Momo runtime, trust injected MCP credentials, workspace, and route context until a business tool explicitly reports otherwise.
+Assumes MCP is connected, authenticated, and on the correct workspace.
 Before routing, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
 
 ## Default Paths
 
 Route to exactly one of these specialized paths:
 
-1. Record insert
+1. Record insert  
    Switch to [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
 
-2. Record update
+2. Record update  
    Switch to [$qingflow-record-update](../qingflow-record-update/SKILL.md)
 
-3. Record delete
+3. Record delete  
    Switch to [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
 
-4. Record import
+4. Record import  
    Switch to [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 
-5. Task workflow operations
+5. Task workflow operations  
    Switch to [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 
-6. Analysis
+6. Analysis  
    Switch to [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
 
-7. Standalone MCP setup or explicit auth/workspace recovery
+7. MCP connection / auth / workspace selection  
    Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
 
 8. App / view / workflow / chart / portal / package configuration
-   This is outside the App User MCP tool surface. Use the separate `qingflow-app-builder` skill/MCP package when that builder surface is installed; otherwise ask the user to enable the builder MCP.
+   This is builder work, not app-user work. Use the `qingflow-cli` skill or install/use the `qingflow-app-builder` package.
 
 ## Routing Rules
 
-- If the user does not know the target `app_key`, discover apps first with `app_list` / `app list --query` over current-user visible apps, then route to the specialized skill; do not use the legacy app search path for ordinary members
+- If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
 - If the task is about creating or new record entry, switch to `$qingflow-record-insert`
 - If the task is about editing an existing record directly, switch to `$qingflow-record-update`
 - If the task is about deleting records directly, switch to `$qingflow-record-delete`
 - If the task is about import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-import`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
-- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, do not continue with App User MCP tools. Use the separate `qingflow-app-builder` skill/MCP package when available, or ask the user to enable the builder MCP.
+- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, stop this app-user route and use the `qingflow-cli` skill or the `qingflow-app-builder` package
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
-- For member/department field ambiguity, keep the record insert/update route and use `record_member_candidates` / `record_department_candidates`; do not switch to `directory_*`, builder member search, external-contact lookup, or contact-directory management queries. App User MCP only exposes `directory_search` for member-visible keyword search, not directory tree/list management.
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
 - If the task is about subtable writes, still route to the matching insert/update skill, but shape the payload as parent subtable field -> row array; do not route users toward top-level leaf selectors
 - If the task is insert-focused and readback/detail context matters, keep the same route and prefer the single-record detail readback after the write; use normalized list readback only when batch row shape is needed
 - If the user sounds like an ordinary workflow assignee rather than a system operator, prefer `$qingflow-task-ops` over direct record mutation whenever both paths could fit
 - If the task is about task discovery by natural language query, still route to `$qingflow-task-ops`; `task_list --query` now uses backend search first and only falls back to local matching when backend returns zero rows
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
-- In Wingent Momo runtime, do not route to `$qingflow-mcp-setup` as a preflight. Switch there only when a business tool explicitly reports missing auth, invalid session, or wrong/missing workspace, or when the user asks to configure a standalone MCP client.
+- If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
 
 ## Shared Preconditions
 
@@ -89,4 +88,4 @@ Route to exactly one of these specialized paths:
 - Record import: [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 - Task workflow operations: [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 - Dedicated analysis workflow: [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
-- Builder workflow requires the separate `qingflow-app-builder` skill/MCP package.
+- Builder workflow: use the `qingflow-cli` skill or the `qingflow-app-builder` package

package/skills/qingflow-app-user/references/data-gotchas.md

@@ -9,12 +9,12 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 - `record_get` is for one exact record and downloads readable detail-page images into `media_assets.items[].local_path` plus attachments/documents/tables into `file_assets.items[].local_path`
 - Use `record_browse_schema_get` when field titles are uncertain instead of guessing ids
 - Do not present paged browse output as if it were a grouped or full-population conclusion
-- Use `record_export_direct` only when the user explicitly asks for export/download/Excel output, and always pass an explicit `view_id` from `app_get.accessible_views` or the frontend URL
+- Use `record_export_direct` only when the user explicitly asks for export/download/Excel output
 
 ## Direct Writes
 
 - `record_insert` is schema-first through `record_insert_schema_get`; default to `items=[{"fields": {...}}]`
-- `record_update` is detail-first: read `record_get`, compose the requested title-keyed `fields` map, then write directly; use `record_update_schema_get` only after update failure or ambiguity
+- `record_update` is schema-first through `record_update_schema_get`
 - `record_delete` does not need a schema-get step
 - For batch insert, `partial_success` means some rows were created; use `created_record_ids`, failed `row_number`, and `failed_fields` to repair only failed rows
 - If a direct-write tool returns `write_executed=false`, the write was blocked and not executed for that item

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -1,6 +1,6 @@
 # Qingflow Core Public Surface Sync
 
-Use this file as the maintenance baseline for the core Qingflow skills.
+Use this file as the maintenance baseline for the core Qingflow skills.  
 It is not a user-facing product spec. It exists to prevent skill drift.
 
 ## Current Public Defaults
@@ -12,9 +12,9 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 - Standard flows:
   - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
   - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
-  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
+  - explicit export/download/Excel: `view_get -> record_export_*` or `record_export_direct`
   - insert: `record_insert_schema_get -> record_insert(items)`
-  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
+  - update: `record_update_schema_get -> record_update`
 
 ### Tasks
 
@@ -33,20 +33,22 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 
 ### Builder
 
+- Builder work belongs to the `qingflow-cli` skill or the `qingflow-app-builder` package; this app-user package only records the boundary to prevent routing drift.
 - Official package entry: `package_get`, `package_apply`
 - Official builder writes:
   - `app_schema_apply`
   - `app_layout_apply`
   - `app_flow_apply`
   - `app_views_apply`
-  - `app_custom_buttons_apply`
   - `app_associated_resources_apply`
   - `app_charts_apply`
   - `portal_apply`
   - `app_publish_verify`
+- Complete-system main path: package -> schema apps with `form.sections` and `target_app_ref` -> views with `action_buttons` -> portal with inline `sections[].chart`
+- Single-app main path: resolve/get -> schema with `form.sections` -> views with `action_buttons`; do not default to portal
 - `portal_apply` edit mode may omit `sections` for base-info-only updates
 - `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- Existing object parameter replacement should use `patch_views`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
 - `app_get.editability` uses:
   - `can_edit_app_base`
   - `can_edit_form`

package/skills/qingflow-app-user/references/record-patterns.md

@@ -41,13 +41,13 @@ Use `record_insert_schema_get -> record_insert(items)`.
 
 ## Update Pattern
 
-Use `record_get -> record_update`.
+Use `record_update_schema_get -> record_update`.
 
 1. Confirm the target app and `record_id`
-2. Read `record_get` in the same view/context the user is using when a `view_id` is known
-3. Build a field-title keyed `fields` map from `record_get.fields[]` and the user's requested changes
-4. Run `record_update` directly; let MCP auto-select the executable update route
-5. If `record_update` fails because fields/routes are ambiguous or unavailable, then use `record_update_schema_get` as a diagnostic tool
+2. Read `writable_fields` and `payload_template`
+3. Update only fields present in `writable_fields`
+4. Let MCP auto-select the first matched accessible view that can execute the payload
+5. Run `record_update`
 
 ## Delete Pattern
 

package/skills/qingflow-app-user/references/workflow-usage.md

@@ -14,12 +14,13 @@ Examples:
 
 Rules:
 
-- if the user starts from inbox, todo, workload, cc, or bottleneck language, use the public task tools first
-- use `task_list` for headline counts and flat browsing; group locally by app or workflow node when buckets matter
-- use `task_get`, `task_workflow_log_get`, and `task_associated_report_detail_get` only after locating the exact task
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
+- use `task_summary` for headline counts
+- use `task_list` for flat browsing
+- use `task_facets` when worksheet or workflow-node buckets matter
 - treat task counts as task-center counts, not record counts
 - switch to `record_*` only after locating the exact business record behind a task
 - identify the exact target first
-- for approve or reject, identify the exact target first; prefer `task_id` from task-center results, then use `task_action_execute` with action `approve` or `reject`
+- for approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
 - avoid usage-side workflow actions on ambiguous records
 - summarize the final action and target task ids or record ids