@qingflow-tech/qingflow-app-user-mcp 1.0.10 → 1.0.12

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -0,0 +1,77 @@
+# Q-Linker Builder Notes
+
+## What Builder Should Configure
+
+- `remoteLookupConfig`
+- alias parsing
+- target field binding
+- auto trigger
+- custom button text
+
+## Current Supported Scope
+
+- custom mode only
+- standard request fields
+- alias path parsing
+- target field binding to existing ordinary fields
+
+## Recommended Public APIs For Samples
+
+### Httpbin
+
+- URL: `https://httpbin.org/get`
+- Good for:
+  - query echo
+  - request URL echo
+
+Useful paths:
+- `$.args.keyword`
+- `$.url`
+
+### Open-Meteo Geocoding
+
+- URL: `https://geocoding-api.open-meteo.com/v1/search`
+- Good for:
+  - place normalization
+  - country
+  - lat/lng summary
+
+Useful paths:
+- `$.results[0].name`
+- `$.results[0].country`
+- `$.results[0].latitude`
+- `$.results[0].longitude`
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Prefer:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Avoid:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `app_get_fields`
+- `record_insert_schema_get`
+- `record_insert`
+
+This verifies that the configuration does not break the form page, even before runtime execution is tested.

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

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 metadata:
   short-description: Router for Qingflow operational skills
 ---
@@ -10,32 +10,32 @@ metadata:
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.
-Assumes MCP is connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust injected MCP credentials, workspace, and route context until a business tool explicitly reports otherwise.
 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. MCP connection / auth / workspace selection  
+7. Standalone MCP setup or explicit auth/workspace recovery
    Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
 
 8. App / view / workflow / chart / portal / package configuration
@@ -43,7 +43,7 @@ Route to exactly one of these specialized paths:
 
 ## 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 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 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`
@@ -52,13 +52,14 @@ Route to exactly one of these specialized paths:
 - 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, switch to `$qingflow-app-builder`
 - 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`
-- If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
+- 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.
 
 ## Shared Preconditions
 

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
+- 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
 
 ## Direct Writes
 
 - `record_insert` is schema-first through `record_insert_schema_get`; default to `items=[{"fields": {...}}]`
-- `record_update` is schema-first through `record_update_schema_get`
+- `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_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: `view_get -> record_export_*` or `record_export_direct`
+  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
   - insert: `record_insert_schema_get -> record_insert(items)`
-  - update: `record_update_schema_get -> record_update`
+  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
 
 ### Tasks
 

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_update_schema_get -> record_update`.
+Use `record_get -> record_update`.
 
 1. Confirm the target app and `record_id`
-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`
+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
 
 ## Delete Pattern
 

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

@@ -14,13 +14,12 @@ Examples:
 
 Rules:
 
-- 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
+- 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
 - 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 `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
+- 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`
 - avoid usage-side workflow actions on ambiguous records
 - summarize the final action and target task ids or record ids

package/skills/qingflow-mcp-setup/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: qingflow-mcp-setup
+description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
+metadata:
+  short-description: Install and connect the Qingflow MCP locally
+---
+
+# Qingflow MCP Setup
+
+## Overview
+
+This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
+
+## Workflow
+
+Follow these steps in order.
+
+`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+
+Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+### Step 1: Verify the local project path
+
+Resolve the repository root first. In this repo, the MCP server should live at:
+
+- `<repo_root>/qingflow-support/mcp-server`
+
+Key entrypoint:
+
+- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+
+If the path differs, stop and update all client config snippets before proceeding.
+If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
+
+### Step 2: Install local dependencies
+
+Run:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
+
+### Step 3: Configure the local AI client
+
+For any stdio-compatible MCP client, map these values:
+
+- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
+- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
+
+Client-specific snippets:
+
+- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
+
+When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
+
+### Step 4: Validate startup
+
+The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
+
+Manual startup command:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+Prefer validating through the client after config is added.
+
+### Step 5: Use injected session first; authenticate only for setup or recovery
+
+For Wingent Momo runtime conversations, the session normally already carries the credential-derived token, workspace, and route context. Do not run `auth_use_credential`, `auth_login`, `workspace_list`, or `workspace_select` before ordinary business tools. Start with the smallest read-only business call that fits the task; if it succeeds, continue.
+
+For a standalone local MCP client that has no injected session, use this setup order:
+
+1. `auth_use_credential` or `auth_login`
+2. `workspace_list`
+3. `workspace_select`
+4. Run a small read-only business tool
+
+`auth_use_credential` gets the selected workspace from the credential context. If the user needs a different workspace after authentication, use `workspace_list` and then `workspace_select`.
+After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
+`auth_use_credential` is a tool call, not a custom HTTP header. It exchanges the createClaw credential for a Qingflow token, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
+Do not run `workspace_select` on production paths unless the user explicitly asks to switch workspace or a business tool clearly reports that no workspace is selected. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+
+### Step 6: Troubleshoot in the right layer
+
+- If the client cannot launch the server, check path, execute permission, and `.venv`
+- If tools return `auth required`, re-run `auth_use_credential` or `auth_login`
+- If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
+- If calls fail after a working session, assume token expiry and re-authenticate
+- If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
+
+## Guardrails
+
+- Never write tokens into the skill files
+- In Wingent Momo runtime, trust injected workspace context until a business tool proves otherwise; for standalone clients, confirm workspace with `auth_whoami`, `workspace_select`, or a successful read-only business call.
+- When debugging, distinguish server startup issues from Qingflow auth issues
+- When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
+- If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
+- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow MCP Setup"
+  short_description: "Install and connect the Qingflow MCP locally"
+  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -0,0 +1,34 @@
+# Claude Desktop
+
+Use this when the user wants to install Qingflow MCP in Claude Desktop.
+
+## Config snippet
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
+      }
+    }
+  }
+}
+```
+
+## Environment examples
+
+- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
+- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
+
+Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
+
+## Notes
+
+- After updating the config, restart Claude Desktop
+- Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
+- If the server path changes, update the `command` field
+- The server is local stdio MCP, so no remote URL is required
+- Do not store Qingflow credentials in Claude Desktop config; pass the createClaw credential through `auth_use_credential` inside the chat, or use `auth_login` when credential exchange is unavailable

package/skills/qingflow-mcp-setup/references/environments.md

@@ -0,0 +1,62 @@
+# Environment Switching
+
+Use this reference before any setup, authentication, or live validation flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the user is targeting:
+
+- `test`: for smoke tests, trial setup, DSL validation, mock data, and integration debugging
+- `prod`: for real business usage in the formal environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Default characteristics:
+
+- preferred for first-time setup and local MCP validation
+- mock or smoke data is acceptable when the user asks for it
+- use read/write verification freely inside the intended test workspace
+
+Known values in the current workspace:
+
+- use an explicitly provided non-production backend
+- common test workspace example: `ws_id=2`
+- `qf_version`: usually unset unless the user explicitly needs a routed version
+
+Setup behavior:
+
+- prefer this environment for Claude Desktop or local MCP client onboarding
+- for Wingent Momo runtime, use the injected session and skip auth/workspace preflight
+- for standalone MCP client setup, use `auth_use_credential` or `auth_login`, then `workspace_list`, then `workspace_select`
+- if the user asks to verify installation, a real read-only smoke path is acceptable
+
+## Production Environment
+
+Production is the default environment when the user does not specify one. If the user explicitly says `test`, switch to the dedicated non-production backend they provide.
+
+Expected behavior:
+
+- default `base_url`: `https://qingflow.com/api`
+- confirm the production `qf_version` explicitly when browser traffic depends on routed versions such as `canary`
+- confirm the exact workspace before any live validation
+- prefer read-only checks first
+- avoid mock data, smoke writes, or destructive tests unless the user explicitly asks for them
+
+Production guardrails:
+
+- do not store credentials in skill files or examples
+- do not assume the same workspace ids as test
+- treat startup verification and auth verification as separate steps
+- when sharing snippets, label them as `prod` and `test` clearly
+- when MCP and browser results diverge, compare `request_route` with the browser route before blaming the query logic
+
+## Reporting Rule
+
+When you give setup instructions, always state:
+
+- active environment
+- selected `base_url`
+- selected `qf_version` when relevant
+- whether the next step is read-only or write-impacting

package/skills/qingflow-mcp-setup/references/generic-stdio.md

@@ -0,0 +1,32 @@
+# Generic Stdio MCP Clients
+
+Use this for any local AI client that supports MCP over stdio.
+
+## Required mapping
+
+- `command`: `<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: backend base URL for the active environment
+
+Environment examples:
+
+- `prod` (default): `https://qingflow.com/api`
+- `test`: use the explicitly provided non-production backend
+
+Keep separate client entries or separate config snippets for `test` and `prod`.
+
+## Validation sequence
+
+1. Start the client
+2. Confirm the `qingflow` MCP server is visible
+3. In Wingent Momo runtime, skip auth/workspace preflight and run a read-only tool such as `app_list`
+4. In a standalone client without injected credentials, run `auth_use_credential` or `auth_login`
+5. Then run `workspace_list`
+6. Then run `workspace_select`
+7. Run a read-only tool such as `app_list`
+
+## Common failures
+
+- Launch failure: bad `command` path or missing `.venv`
+- Auth failure: invalid or expired credential/token
+- Business tool failure before setup: workspace not selected

package/skills/qingflow-mcp-setup/scripts/check_local_server.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${QINGFLOW_MCP_ROOT:-}"
+
+if [[ -z "$ROOT" ]]; then
+  if git_root="$(git rev-parse --show-toplevel 2>/dev/null)" && [[ -d "$git_root/qingflow-support/mcp-server" ]]; then
+    ROOT="$git_root/qingflow-support/mcp-server"
+  elif [[ -d "$PWD/qingflow-support/mcp-server" ]]; then
+    ROOT="$PWD/qingflow-support/mcp-server"
+  else
+    repo_root="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+    if [[ -d "$repo_root/qingflow-support/mcp-server" ]]; then
+      ROOT="$repo_root/qingflow-support/mcp-server"
+    fi
+  fi
+fi
+
+if [[ -z "$ROOT" ]]; then
+  echo "Unable to locate qingflow-support/mcp-server. Set QINGFLOW_MCP_ROOT to the repo copy of the MCP server." >&2
+  exit 1
+fi
+
+ENTRY="$ROOT/qingflow-mcp"
+PY="$ROOT/.venv/bin/python"
+
+echo "ROOT=$ROOT"
+test -d "$ROOT"
+echo "OK root exists"
+
+test -x "$ENTRY"
+echo "OK entrypoint exists and is executable"
+
+test -x "$PY"
+echo "OK virtualenv python exists"
+
+PYTHONPATH="$ROOT/src" "$PY" -c "import qingflow_mcp.server; print('OK import qingflow_mcp.server')"

package/skills/qingflow-record-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-record-analysis
-description: Analyze Qingflow record data safely after the MCP is already connected and authenticated. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
+description: Analyze Qingflow record data safely. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
 metadata:
   short-description: Analyze Qingflow record data with record_access CSV and Python
 ---
@@ -20,7 +20,7 @@ app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pand
 ```bash
 qingflow record --help
 qingflow record access --help
-qingflow record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json --json
+qingflow --json record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json
 ```
 
 The CLI command is under the `record` command group, so the discovery path is: first inspect `qingflow record --help`, then inspect `qingflow record access --help`.
@@ -40,7 +40,7 @@ The CLI command is under the `record` command group, so the discovery path is: f
 - `record_list` is only for sample inspection after the aggregate result is understood.
 - `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
 - `record_export_direct` is only for explicit export/download/Excel requests.
-- `chart_get` / QingBI is only for user-provided report URLs or chart ids.
+- `chart_get` / QingBI is only for user-provided report URLs or chart ids. If it reports `CHART_BASE_INFO_UNAVAILABLE` but `chart_data_loaded=true`, treat the chart data as readable and only the metadata/base info as degraded.
 
 ## Tool Selection
 
@@ -49,7 +49,7 @@ The CLI command is under the `record` command group, so the discovery path is: f
 | Batch analysis, statistics, comparison, report | `record_access -> Python` |
 | Browse a few example rows | `record_list` |
 | Inspect one record, logs, references, images, attachments | `record_get` |
-| User asks to export/download/Excel | `record_export_direct` |
+| User asks to export/download/Excel | `record_export_direct` with explicit `view_id` |
 | User gives report URL or chart id | `chart_get` |
 | Todo/workflow task actions | `$qingflow-task-ops` |
 
@@ -84,13 +84,12 @@ CSV columns are already readable and field-id anchored, for example `项目状
 For CLI use, write JSON argument files instead of embedding large JSON in shell text:
 
 ```bash
-qingflow record access \
+qingflow --json record access \
   --app-key APP_KEY \
   --view-id system:all \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --order-by-file order_by.json
 ```
 
 ## Status Handling

package/skills/qingflow-record-analysis/manifest.yaml

@@ -0,0 +1,10 @@
+identity: qingflow-record-analysis
+type: skill
+description: Analyze Qingflow record data safely. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
+tags:
+  - cli
+  - qingflow
+  - task-management
+  - data-analysis
+  - security
+  - validated

package/skills/qingflow-record-delete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-record-delete
-description: Delete Qingflow records safely after the MCP is already connected and authenticated.
+description: Delete Qingflow records safely using the current Wingent Momo runtime MCP session; recover auth/workspace only after a tool error.
 metadata:
   short-description: Qingflow record delete
 ---
@@ -21,9 +21,11 @@ metadata:
 
 1. Resolve the exact target `record_id` first
 2. Prefer reading the current state before delete when the request is high risk
-3. Call `record_delete` with `record_id` or `record_ids`
+3. Choose an accessible system `view_id` from `app_get.accessible_views`; custom views can locate records but cannot be used as the delete route
+4. Call `record_delete` with `record_id` or `record_ids` and the system `view_id` so the backend uses the matching listType delete route
 
 ## Do Not
 
-- Do not pass any `view_*` selector
+- Do not pass `custom:*` view selectors to `record_delete`; custom views can locate records, but delete currently supports only system listType routes
+- Do not omit `view_id`; a delete without frontend list context is ambiguous and should return `RECORD_DELETE_VIEW_REQUIRED`
 - Do not infer the target record id from a vague title if `record_list` can disambiguate it

package/skills/qingflow-record-import/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-record-import
-description: Explain and operate Qingflow file-based bulk import after the MCP is already connected and authenticated.
+description: Explain and operate Qingflow file-based bulk import using the current Wingent Momo runtime MCP session; recover auth/workspace only after a tool error.
 metadata:
   short-description: Qingflow bulk import workflow and troubleshooting
 ---
@@ -28,4 +28,8 @@ metadata:
 3. Keep official headers unchanged
 4. Verify before start
 5. Only repair a file after explicit user authorization
-6. Read back one imported sample after success
+6. After success, report the import status and tracking identifiers; read back one imported sample only when the user asks for row-level confirmation or when the import result does not already prove completion
+
+## Template Fallback
+
+`record_import_template_get` may return `status: partial_success` with a locally generated applicant template when the official template endpoint is permission-restricted but applicant fields are readable. If the warning is `IMPORT_TEMPLATE_LOCAL_FALLBACK_AUTH_UNKNOWN` or `verification.import_auth_prechecked` is false, treat the result only as "template file prepared"; actual import permission is still decided by `record_import_verify` and `record_import_start`.