@qingflow-tech/qingflow-app-builder-mcp 1.0.11 → 1.0.13

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.11
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.13
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.11 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.13 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -28,5 +28,8 @@ Bundled skills:
 Note:
 
 - The skill files are included in the npm package.
-- On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).
+- Installing the npm package does not overwrite agent skills automatically.
+- To mount bundled skills from an installed package, run `qingflow-app-builder-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-builder-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.
 - 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,7 +101,51 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+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 @josephyan/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
 
 ## 本地验证
 
@@ -110,24 +154,31 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 ```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 安装到某个空目录，命令通常位于：

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 import main
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()

package/npm/bin/qingflow-skills.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { getPackageRoot, runSkillsCli } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+runSkillsCli(packageRoot, process.argv.slice(2));

package/npm/lib/runtime.mjs

@@ -43,29 +43,320 @@ export function getCodexHome() {
   return path.join(home, ".codex");
 }
 
-export function installBundledSkills(packageRoot) {
+function getHomeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve user home because HOME is not set.");
+  }
+  return home;
+}
+
+function getAgentSkillDest(agent, scope, cwd = process.cwd()) {
+  const normalizedAgent = agent.trim().toLowerCase();
+  const normalizedScope = scope.trim().toLowerCase();
+  const home = getHomeDir();
+  if (!["user", "project"].includes(normalizedScope)) {
+    throw new Error(`Unsupported skills scope '${scope}'. Expected 'user' or 'project'.`);
+  }
+
+  const projectRoots = {
+    codex: [cwd, ".codex", "skills"],
+    claude: [cwd, ".claude", "skills"],
+    "claude-code": [cwd, ".claude", "skills"],
+    cursor: [cwd, ".cursor", "skills"],
+    generic: [cwd, ".agents", "skills"],
+  };
+  const userRoots = {
+    codex: [process.env.CODEX_HOME?.trim() || path.join(home, ".codex"), "skills"],
+    claude: [home, ".claude", "skills"],
+    "claude-code": [home, ".claude", "skills"],
+    cursor: [home, ".cursor", "skills"],
+    generic: [home, ".agents", "skills"],
+  };
+
+  const roots = normalizedScope === "project" ? projectRoots : userRoots;
+  const parts = roots[normalizedAgent];
+  if (!parts) {
+    throw new Error(`Unsupported skills agent '${agent}'. Expected one of: codex, claude, claude-code, cursor, generic.`);
+  }
+  return path.resolve(...parts);
+}
+
+export function listBundledSkills(packageRoot) {
   const skillsSrc = path.join(packageRoot, "skills");
   if (!fs.existsSync(skillsSrc)) {
-    return { installed: [], skipped: true, destination: null };
+    return [];
   }
 
-  const codexHome = getCodexHome();
-  const skillsDestRoot = path.join(codexHome, "skills");
-  fs.mkdirSync(skillsDestRoot, { recursive: true });
+  return fs
+    .readdirSync(skillsSrc, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillsSrc, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function sameRealPath(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch {
+    return false;
+  }
+}
 
-  const installed = [];
-  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) {
-      continue;
+function installOneSkill(src, dest, { force, mode }) {
+  let existingStat = null;
+  try {
+    existingStat = fs.lstatSync(dest);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  if (existingStat) {
+    if (existingStat.isSymbolicLink() && sameRealPath(dest, src)) {
+      return { status: "unchanged" };
+    }
+    if (!force) {
+      return { status: "conflict" };
     }
-    const src = path.join(skillsSrc, entry.name);
-    const dest = path.join(skillsDestRoot, entry.name);
     fs.rmSync(dest, { recursive: true, force: true });
+  }
+
+  if (mode === "copy") {
     fs.cpSync(src, dest, { recursive: true });
-    installed.push(entry.name);
+    return { status: "installed" };
+  }
+
+  fs.symlinkSync(src, dest, "dir");
+  return { status: "installed" };
+}
+
+function writeSkillProvenance(skillsDestRoot, skillName, payload) {
+  const provenanceRoot = path.join(skillsDestRoot, ".qingflow-skill-sources");
+  fs.mkdirSync(provenanceRoot, { recursive: true });
+  fs.writeFileSync(path.join(provenanceRoot, `${skillName}.json`), `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+export function installBundledSkills(
+  packageRoot,
+  {
+    agent = "codex",
+    scope = "user",
+    mode = "symlink",
+    force = false,
+    skills = [],
+    cwd = process.cwd(),
+  } = {},
+) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], unchanged: [], conflicts: [], skipped: true, destination: null };
   }
 
-  return { installed, skipped: false, destination: skillsDestRoot };
+  const validModes = new Set(["symlink", "copy"]);
+  if (!validModes.has(mode)) {
+    throw new Error(`Unsupported skills install mode '${mode}'. Expected 'symlink' or 'copy'.`);
+  }
+
+  const available = listBundledSkills(packageRoot);
+  const wanted = skills.length ? skills : available;
+  const unknown = wanted.filter((skillName) => !available.includes(skillName));
+  if (unknown.length) {
+    throw new Error(`Unknown bundled skill(s): ${unknown.join(", ")}. Available: ${available.join(", ")}`);
+  }
+
+  const skillsDestRoot = getAgentSkillDest(agent, scope, cwd);
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  const result = {
+    installed: [],
+    unchanged: [],
+    conflicts: [],
+    skipped: false,
+    destination: skillsDestRoot,
+    agent,
+    scope,
+    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 result;
+}
+
+function parseSkillsCliArgs(args) {
+  const parsed = {
+    command: "help",
+    agent: "codex",
+    scope: "user",
+    mode: "symlink",
+    force: false,
+    json: false,
+    skills: [],
+  };
+  const rest = [...args];
+  if (rest.length && !rest[0].startsWith("-")) {
+    parsed.command = rest.shift();
+  }
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const next = () => {
+      index += 1;
+      if (index >= rest.length) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+      return rest[index];
+    };
+    switch (arg) {
+      case "--agent":
+      case "-a":
+        parsed.agent = next();
+        break;
+      case "--scope":
+      case "-s":
+        parsed.scope = next();
+        break;
+      case "--mode":
+      case "-m":
+        parsed.mode = next();
+        break;
+      case "--skill":
+        parsed.skills.push(next());
+        break;
+      case "--all":
+        parsed.agent = "all";
+        break;
+      case "--force":
+      case "-f":
+        parsed.force = true;
+        break;
+      case "--copy":
+        parsed.mode = "copy";
+        break;
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--help":
+      case "-h":
+        parsed.command = "help";
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option ${arg}`);
+        }
+        parsed.skills.push(arg);
+        break;
+    }
+  }
+  return parsed;
+}
+
+function printSkillsHelp() {
+  console.log(`Qingflow bundled skills
+
+Usage:
+  qingflow-skills list [--json]
+  qingflow-skills install [--agent codex|claude|claude-code|cursor|generic|all] [--scope user|project] [--mode symlink|copy] [--skill name] [--force] [--json]
+
+Examples:
+  qingflow-skills list
+  qingflow-skills install --agent codex --scope user
+  qingflow-skills install --agent claude-code --scope project --copy
+  qingflow-skills install --agent all --scope project
+
+Defaults:
+  --agent codex
+  --scope user
+  --mode symlink
+
+Existing skills are not overwritten unless --force is provided.`);
+}
+
+function printInstallSummary(result) {
+  console.log(`[qingflow-skills] destination: ${result.destination}`);
+  if (result.installed.length) {
+    console.log(`[qingflow-skills] installed: ${result.installed.join(", ")}`);
+  }
+  if (result.unchanged.length) {
+    console.log(`[qingflow-skills] unchanged: ${result.unchanged.join(", ")}`);
+  }
+  if (result.conflicts.length) {
+    console.log(`[qingflow-skills] conflicts: ${result.conflicts.join(", ")}`);
+    console.log("[qingflow-skills] Re-run with --force to replace conflicting skills.");
+  }
+}
+
+export function runSkillsCli(packageRoot, args) {
+  let parsed;
+  try {
+    parsed = parseSkillsCliArgs(args);
+    if (parsed.command === "help") {
+      printSkillsHelp();
+      return;
+    }
+    if (parsed.command === "list") {
+      const skills = listBundledSkills(packageRoot);
+      if (parsed.json) {
+        console.log(JSON.stringify({ skills }, null, 2));
+      } else {
+        for (const skill of skills) {
+          console.log(skill);
+        }
+      }
+      return;
+    }
+    if (parsed.command !== "install") {
+      throw new Error(`Unknown qingflow skills command '${parsed.command}'.`);
+    }
+
+    const agents = parsed.agent === "all" ? ["codex", "claude-code", "cursor", "generic"] : [parsed.agent];
+    const results = agents.map((agent) =>
+      installBundledSkills(packageRoot, {
+        agent,
+        scope: parsed.scope,
+        mode: parsed.mode,
+        force: parsed.force,
+        skills: parsed.skills,
+      }),
+    );
+    if (parsed.json) {
+      console.log(JSON.stringify({ results }, null, 2));
+    } else {
+      for (const result of results) {
+        printInstallSummary(result);
+      }
+    }
+    if (results.some((result) => result.conflicts.length)) {
+      process.exit(2);
+    }
+  } catch (error) {
+    if (parsed?.json) {
+      console.error(JSON.stringify({ error: error.message }, null, 2));
+    } else {
+      console.error(`[qingflow-skills] ${error.message}`);
+      console.error("Run 'qingflow-skills --help' for usage.");
+    }
+    process.exit(1);
+  }
 }
 
 export function getVenvDir(packageRoot) {

package/npm/scripts/postinstall.mjs

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

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "qingflow-app-builder-mcp": "./npm/bin/qingflow-app-builder-mcp.mjs"
+    "qingflow-app-builder-mcp": "./npm/bin/qingflow-app-builder-mcp.mjs",
+    "qingflow-app-builder-mcp-skills": "./npm/bin/qingflow-skills.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.0.11"
+version = "1.0.13"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -1,6 +1,6 @@
 ---
 name: qingflow-app-builder
-description: Build, configure, and modify Qingflow apps and systems after the MCP is already connected and authenticated. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
+description: Build, configure, and modify Qingflow apps and systems using the current Wingent Momo runtime MCP session. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
 metadata:
   short-description: Build and modify Qingflow apps and systems
 ---
@@ -10,11 +10,11 @@ metadata:
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
-Assumes MCP is already connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust the injected MCP session, credentials, workspace, and route context until a tool explicitly reports otherwise.
 
 Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
 
-Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md).
+Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
 
 ## Current Public Mental Model
 
@@ -105,14 +105,13 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 
 ## Standard Operating Order
 
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm whether the task is read-only or write-impacting
-4. Resolve the smallest stable target:
+1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
+2. Confirm whether the task is read-only or write-impacting
+3. Resolve the smallest stable target:
    - app-scoped work -> `app_resolve`
    - package-scoped work with known id -> `package_get`
    - portal inventory -> `portal_list`
-5. Read only the smallest config slice needed:
+4. Read only the smallest config slice needed:
    - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
    - fields -> `app_get_fields`
    - layout -> `app_get_layout`
@@ -120,8 +119,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - flow -> `app_get_flow`
    - charts -> `app_get_charts` only when the app_get compact list is not enough
    - portal -> `portal_get`
-6. If the public shape is unclear, call `builder_tool_contract`
-7. Apply the smallest patch tool that fits:
+5. If the public shape is unclear, call `builder_tool_contract`
+6. Apply the smallest patch tool that fits:
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
    - flow -> `app_flow_apply`
@@ -131,11 +130,12 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
-8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
+7. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
 
 ## Safe Usage Rules
 
 - Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
+- Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
 - If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
 - Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
@@ -241,7 +241,7 @@ For add-data buttons that create a child record linked back to the current recor
 
 ## Resources
 
-- Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
+- Shared public-surface baseline: [public-surface-sync.md](references/public-surface-sync.md)
 - Environment switching: [references/environments.md](references/environments.md)
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
 - Field matching rules: [references/match-rules.md](references/match-rules.md)

package/skills/qingflow-app-builder/references/create-app.md

@@ -6,9 +6,9 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create each app separately
+2. create the related apps in one `app_schema_apply(apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add relation fields between apps
+4. add same-call relation fields with `target_app_ref` when one new app references another new app
 
 Hierarchy reminder:
 
@@ -138,7 +138,7 @@ Expected on create. Continue with `create_if_missing=true`.
 
 ### `CREATE_APP_ROUTE_NOT_FOUND`
 
-The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
+The create route did not resolve in the current backend route context. In Wingent Momo runtime, first retry the same `app_schema_apply` after confirming the injected session is still active. Only run `workspace_select` if a business tool explicitly reports a missing or wrong workspace.
 
 ### Hierarchy modeling mistake
 

package/skills/qingflow-app-builder/references/environments.md

@@ -16,7 +16,7 @@ If the user did not specify an environment, default to `prod`.
 Use test for:
 
 - first application of a new `SolutionSpec`
-- trying `solution_build_all(..., verify=true)`
+- trying builder apply flows end-to-end with readback verification, or `solution_install` when the user is installing an existing packaged solution
 - package initialization and schema evolution experiments
 - mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
 

package/skills/qingflow-app-builder/references/gotchas.md

@@ -3,7 +3,7 @@
 ## Auth and workspace
 
 - `auth_*` success does not mean a workspace is selected
-- Re-run `workspace_select` after auth changes or route changes
+- In Wingent Momo runtime, do not run `workspace_select` before builder work. Re-run it only after an explicit auth/route recovery or when a business tool reports the workspace is missing.
 
 ## Package ownership