@qingflow-tech/qingflow-app-user-mcp 1.0.0

package/npm/lib/runtime.mjs

@@ -0,0 +1,339 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const WINDOWS = process.platform === "win32";
+
+function runChecked(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const details = [result.stderr, result.stdout].filter((value) => typeof value === "string" && value.trim()).join("\n");
+    throw new Error(details ? `Command failed: ${command} ${args.join(" ")}\n${details}` : `Command failed: ${command} ${args.join(" ")}`);
+  }
+}
+
+function commandWorks(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+export function getPackageRoot(metaUrl) {
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
+}
+
+export function getCodexHome() {
+  const configured = process.env.CODEX_HOME?.trim();
+  if (configured) {
+    return path.resolve(configured);
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve CODEX_HOME because HOME is not set.");
+  }
+  return path.join(home, ".codex");
+}
+
+export function installBundledSkills(packageRoot) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], skipped: true, destination: null };
+  }
+
+  const codexHome = getCodexHome();
+  const skillsDestRoot = path.join(codexHome, "skills");
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const installed = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const src = path.join(skillsSrc, entry.name);
+    const dest = path.join(skillsDestRoot, entry.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    installed.push(entry.name);
+  }
+
+  return { installed, skipped: false, destination: skillsDestRoot };
+}
+
+export function getVenvDir(packageRoot) {
+  return path.join(packageRoot, ".npm-python");
+}
+
+export function getVenvPython(packageRoot) {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", "python.exe")
+    : path.join(getVenvDir(packageRoot), "bin", "python");
+}
+
+export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp") {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", `${commandName}.exe`)
+    : path.join(getVenvDir(packageRoot), "bin", commandName);
+}
+
+function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  try {
+    const payload = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return typeof payload.version === "string" && payload.version.trim() ? payload.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readBootstrapStamp(stampPath) {
+  if (!fs.existsSync(stampPath)) {
+    return { exists: false, version: null };
+  }
+  try {
+    const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+    const version = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
+    return { exists: true, version };
+  } catch {
+    return { exists: true, version: null };
+  }
+}
+
+export function inspectPythonEnv(packageRoot, commandName = "qingflow-mcp") {
+  const venvDir = getVenvDir(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot, commandName);
+  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const packageVersion = readPackageVersion(packageRoot);
+  const stamp = readBootstrapStamp(stampPath);
+  const problems = [];
+
+  if (!packageVersion) {
+    problems.push("package-version-missing");
+  }
+  if (!fs.existsSync(serverCommand)) {
+    problems.push("server-command-missing");
+  }
+  if (!stamp.exists) {
+    problems.push("bootstrap-stamp-missing");
+  } else if (!stamp.version) {
+    problems.push("bootstrap-stamp-invalid");
+  } else if (packageVersion && stamp.version !== packageVersion) {
+    problems.push("bootstrap-version-mismatch");
+  }
+
+  return {
+    ready: problems.length === 0,
+    packageVersion,
+    stampVersion: stamp.version,
+    stampExists: stamp.exists,
+    stampPath,
+    serverCommand,
+    venvDir,
+    problems,
+  };
+}
+
+function formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap = false } = {}) {
+  const problemLines = [];
+  for (const problem of runtime.problems) {
+    switch (problem) {
+      case "package-version-missing":
+        problemLines.push("- package.json is missing a valid version field");
+        break;
+      case "server-command-missing":
+        problemLines.push(`- missing Python entrypoint: ${runtime.serverCommand}`);
+        break;
+      case "bootstrap-stamp-missing":
+        problemLines.push(`- missing bootstrap stamp: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-stamp-invalid":
+        problemLines.push(`- bootstrap stamp is unreadable or invalid: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-version-mismatch":
+        problemLines.push(
+          `- bootstrap version mismatch: package=${runtime.packageVersion ?? "unknown"}, runtime=${runtime.stampVersion ?? "unknown"}`
+        );
+        break;
+      default:
+        problemLines.push(`- ${problem}`);
+        break;
+    }
+  }
+
+  const action = allowRuntimeBootstrap
+    ? "Delete .npm-python and retry, or rerun npm install to rebuild the embedded Python runtime."
+    : "Delete .npm-python and rerun npm install, or reinstall the npm package before starting the MCP server.";
+
+  const bootstrapNote = allowRuntimeBootstrap
+    ? ""
+    : "\nRuntime bootstrap is disabled for stdio MCP entrypoints so install logs can never corrupt the MCP stdout transport.";
+
+  return [
+    `[qingflow-mcp] Python runtime for ${commandName} is not ready.`,
+    ...problemLines,
+    action + bootstrapNote,
+  ].join("\n");
+}
+
+function getVenvPip(packageRoot) {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", "pip.exe")
+    : path.join(getVenvDir(packageRoot), "bin", "pip");
+}
+
+export function findPython() {
+  const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
+  const candidates = preferred
+    ? [{ command: preferred, args: [], label: preferred }]
+    : WINDOWS
+      ? [
+          { command: "py", args: ["-3", "-V"], label: "py -3" },
+          { command: "python", args: ["-V"], label: "python" },
+          { command: "python3", args: ["-V"], label: "python3" },
+        ]
+      : [
+          { command: "python3", args: ["-V"], label: "python3" },
+          { command: "python", args: ["-V"], label: "python" },
+        ];
+
+  for (const candidate of candidates) {
+    if (commandWorks(candidate.command, candidate.args)) {
+      if (candidate.command === "py") {
+        return { command: "py", args: ["-3"], label: candidate.label };
+      }
+      return { command: candidate.command, args: [], label: candidate.label };
+    }
+  }
+
+  throw new Error(
+    "Python 3.11+ was not found. Set QINGFLOW_MCP_PYTHON to a Python 3 executable before running npm install."
+  );
+}
+
+export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
+  const python = findPython();
+  const runtime = inspectPythonEnv(packageRoot, commandName);
+  const venvPython = getVenvPython(packageRoot);
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
+
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
+    return serverCommand;
+  }
+
+  if (force && fs.existsSync(venvDir)) {
+    fs.rmSync(venvDir, { recursive: true, force: true });
+  }
+
+  if (!fs.existsSync(venvPython)) {
+    runChecked(python.command, [...python.args, "-m", "venv", venvDir], { cwd: packageRoot });
+  }
+
+  const pip = getVenvPip(packageRoot);
+  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
+
+  fs.writeFileSync(
+    stampPath,
+    JSON.stringify(
+      {
+        installed_at: new Date().toISOString(),
+        installer: "npm",
+        package_version: packageVersion,
+      },
+      null,
+      2
+    )
+  );
+
+  if (!fs.existsSync(serverCommand)) {
+    throw new Error(`Bootstrap finished but ${serverCommand} was not created.`);
+  }
+
+  return serverCommand;
+}
+
+function proxyStreams(child) {
+  if (process.stdin.readable && child.stdin) {
+    process.stdin.pipe(child.stdin);
+    child.stdin.on("error", (error) => {
+      if (error.code !== "EPIPE") {
+        console.error(`[qingflow-mcp] Failed to forward stdin: ${error.message}`);
+      }
+    });
+  } else if (child.stdin) {
+    child.stdin.end();
+  }
+
+  if (child.stdout) {
+    child.stdout.pipe(process.stdout);
+  }
+  if (child.stderr) {
+    child.stderr.pipe(process.stderr);
+  }
+}
+
+function forwardSignal(child, signal) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+export function spawnServer(packageRoot, args, commandName = "qingflow-mcp", { allowRuntimeBootstrap = false } = {}) {
+  let runtime = inspectPythonEnv(packageRoot, commandName);
+  let serverCommand = runtime.serverCommand;
+
+  if (!runtime.ready) {
+    if (!allowRuntimeBootstrap) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+
+    try {
+      serverCommand = ensurePythonEnv(packageRoot, { commandName });
+      runtime = inspectPythonEnv(packageRoot, commandName);
+    } catch (error) {
+      console.error(`[qingflow-mcp] Failed to prepare Python runtime for ${commandName}: ${error.message}`);
+      process.exit(1);
+      return;
+    }
+
+    if (!runtime.ready) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+  }
+
+  const child = spawn(serverCommand, args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: process.env,
+    windowsHide: true,
+  });
+
+  proxyStreams(child);
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+
+  child.on("error", (error) => {
+    console.error(`[qingflow-mcp] Failed to start server: ${error.message}`);
+    process.exit(1);
+  });
+}

package/npm/scripts/postinstall.mjs

@@ -0,0 +1,16 @@
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+
+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);
+  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

@@ -0,0 +1,34 @@
+{
+  "name": "@qingflow-tech/qingflow-app-user-mcp",
+  "version": "1.0.0",
+  "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"
+  },
+  "scripts": {
+    "postinstall": "node ./npm/scripts/postinstall.mjs"
+  },
+  "files": [
+    "README.md",
+    "pyproject.toml",
+    "entry_point.py",
+    "src/qingflow_mcp/**/*.py",
+    "src/qingflow_mcp/py.typed",
+    "qingflow-app-user-mcp",
+    "npm/",
+    "docs/local-agent-install.md",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=16.16.0"
+  },
+  "keywords": [
+    "mcp",
+    "qingflow",
+    "agent",
+    "stdio",
+    "app-user"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qingflow-mcp"
+version = "0.2.0b87"
+description = "User-authenticated MCP server for Qingflow"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+  { name = "Qingflow", email = "support@qingflow.com" }
+]
+keywords = ["mcp", "qingflow", "automation", "workflow"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "mcp>=1.9.4,<2.0.0",
+  "httpx>=0.27,<1.0",
+  "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
+  "pydantic>=2.8,<3.0",
+  "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3,<9.0",
+  "respx>=0.22,<1.0",
+]
+build = [
+  "pyinstaller>=6.0,<7.0",
+  "build>=1.0,<2.0",
+  "twine>=5.0,<6.0",
+]
+
+[project.scripts]
+qingflow-app-user-mcp = "qingflow_mcp.server_app_user:main"
+qingflow-app-builder-mcp = "qingflow_mcp.server_app_builder:main"
+qingflow = "qingflow_mcp.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/qingflow/qingflow-mcp"
+Documentation = "https://github.com/qingflow/qingflow-mcp#readme"
+Repository = "https://github.com/qingflow/qingflow-mcp"
+Issues = "https://github.com/qingflow/qingflow-mcp/issues"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qingflow_mcp = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/qingflow-app-user-mcp

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -n "${PYTHON_BIN:-}" ]]; then
+  PYTHON="${PYTHON_BIN}"
+elif [[ -x "$ROOT_DIR/.venv/bin/python" ]]; then
+  PYTHON="$ROOT_DIR/.venv/bin/python"
+elif command -v python3 >/dev/null 2>&1; then
+  PYTHON="$(command -v python3)"
+else
+  echo "qingflow-app-user-mcp: python interpreter not found. Set PYTHON_BIN or create $ROOT_DIR/.venv" >&2
+  exit 1
+fi
+export PYTHONPATH="$ROOT_DIR/src${PYTHONPATH:+:$PYTHONPATH}"
+exec "$PYTHON" -m qingflow_mcp.server_app_user "$@"

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

@@ -0,0 +1,79 @@
+---
+name: qingflow-app-user
+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
+
+## Overview
+
+This skill is a lightweight router for operational Qingflow work.
+Assumes MCP is connected, authenticated, and on the correct workspace.
+
+## Default Paths
+
+Route to exactly one of these specialized paths:
+
+1. Record insert  
+   Switch to [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
+
+2. Record update  
+   Switch to [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
+
+3. Record delete  
+   Switch to [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
+
+4. Record import  
+   Switch to [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
+
+5. Task workflow operations  
+   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+6. Analysis  
+   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+7. MCP connection / auth / workspace selection  
+   Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
+
+## Routing Rules
+
+- 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 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
+- 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 consistency matters, keep the same route and prefer `record_get / record_list` with `output_profile="normalized"` after the write
+- 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 grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
+- If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
+
+## Shared Preconditions
+
+- prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
+- if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
+- if schema fields include `linkage.sources` or `linkage.affects_fields`, treat those as the preferred high-level explanation of field dependencies instead of trying to infer hidden front-end logic
+- if the task can stay read-only, do not write or act
+- if the task involves a user-uploaded import file, do not modify the file unless the user explicitly authorizes repair or normalization
+- if the task involves record import, call `app_get` first and inspect `data.import_capability` before template download, file repair, or import start
+- if the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Shared Helper
+
+- `feedback_submit` is a cross-cutting helper for product feedback submission
+- It does not require Qingflow login or workspace selection
+- Use it only after the user explicitly confirms they want to submit feedback
+
+## Resources
+
+- Record insert: [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
+- Record update: [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
+- Record delete: [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
+- Record import: [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
+- Dedicated analysis workflow: [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)

package/skills/qingflow-app-user/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App User"
+  short_description: "Route Qingflow operational tasks to insert, update, delete, import, task ops, or analysis"
+  default_prompt: "Use $qingflow-app-user as a router: switch to $qingflow-record-insert for new record entry, $qingflow-record-update for direct edits, $qingflow-record-delete for deletes, $qingflow-record-import for bulk import, $qingflow-task-ops for task-center, comments, directory, and workflow usage actions, and $qingflow-record-analysis for grouped analysis or final statistical conclusions."

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

@@ -0,0 +1,29 @@
+# Data Gotchas
+
+For final statistics, grouped distributions, rankings, trends, or insight-style conclusions, use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
+
+## Record Reads
+
+- `record_list` is for browsing, export, and sample inspection only
+- `record_get` is for one exact record
+- 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
+
+## Direct Writes
+
+- `record_insert` is schema-first through `record_insert_schema_get`
+- `record_update` is schema-first through `record_update_schema_get`
+- `record_delete` does not need a schema-get step
+- If a direct-write tool returns `ok=false`, the write was blocked and not executed
+- Prefer `verify_write=true` for complex, relation-heavy, subtable, or production writes
+
+## Lookup Fields
+
+- Member / department / relation fields may accept natural text, but MCP may return `needs_confirmation`
+- Do not guess ids when the response returns candidate options
+- Retry only after the user confirms the explicit candidate
+
+## Subtables and Attachments
+
+- Subtable payloads stay under the parent table field as a row array
+- Attachment fields are two-step: upload first, then write the returned upload payload

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

@@ -0,0 +1,63 @@
+# Environment Switching
+
+Use this reference before any data creation, update, delete, or workflow usage action.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational data and live workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- mock or smoke data entry
+- business flow walkthroughs
+- user acceptance demos
+- data correction rehearsals
+
+Test behavior:
+
+- creating demo data is acceptable
+- default to at least `5` records for mock or smoke datasets unless the user asks for fewer
+- destructive cleanup is acceptable only when the record scope is explicit
+
+Known current test backend:
+
+- use an explicitly provided non-production backend
+
+## Production Environment
+
+Use production for:
+
+- live data entry
+- live business record updates
+- comments and workflow actions on real records
+- controlled data correction or deletion
+
+Production behavior:
+
+- prefer search or get before any write
+- restate the exact app and record scope before update or delete
+- do not create mock, smoke, or demo data unless the user explicitly asks for it
+- for bulk changes, summarize the target count before execution and the affected ids after execution
+- destructive actions need explicit confirmation in the conversation context
+
+Production guardrails:
+
+- never assume a record id, app id, or workspace id
+- treat `record_delete` as high risk
+- if the task can be answered read-only, do not write
+
+## Reporting Rule
+
+For app-user operations, always report:
+
+- active environment
+- target app
+- operation type: read, create, update, delete, or workflow action
+- affected record count or ids