@josephyan/qingflow-app-builder-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.2
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.21
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.2 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.21 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -19,3 +19,12 @@ Environment:
 - `QINGFLOW_MCP_HOME`
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-builder-mcp` stdio MCP server.
+
+Bundled skills:
+
+- `skills/qingflow-app-builder`
+
+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).

package/npm/lib/runtime.mjs

@@ -29,6 +29,43 @@ 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");
 }

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,10 @@ 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,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "src/qingflow_mcp/py.typed",
     "qingflow-app-builder-mcp",
     "npm/",
-    "docs/local-agent-install.md"
+    "docs/local-agent-install.md",
+    "skills/"
   ],
   "engines": {
     "node": ">=16.16.0"

package/pyproject.toml

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

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

@@ -0,0 +1,225 @@
+---
+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.
+metadata:
+  short-description: Build and modify Qingflow apps and systems
+---
+
+# Qingflow App Builder
+
+## Overview
+
+This skill helps a system builder use the AI-native Qingflow builder surface safely. It assumes the MCP is already connected and authenticated. If not, switch to `$qingflow-mcp-setup` first.
+
+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`.
+
+## Tool Selection
+
+Pick the smallest tool layer that can finish the task.
+
+## Mental Model
+
+Model builder requests in four layers. Do not flatten them.
+
+- `package`: the solution container or app bundle, for example “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package, for example “项目”, “需求”, “任务”, “缺陷”, “团队”
+- `field`: one field inside one app
+- `relation`: a field that links one app to another app
+
+Interpret user intent with this hierarchy:
+
+- If the user says “应用包”, “系统”, “包含多个表单”, “多个模块”, or asks for several named forms that relate to each other, treat it as a `package` with multiple `apps`
+- Do not compress a multi-app system into one app with several text fields
+- Names like “项目/需求/任务/缺陷/团队” or “费用申请/预算管理/报销审批” are usually separate apps, not text fields
+- Build the apps first, then add `relation` fields to connect them
+
+Default modeling rules:
+
+- One business object -> one app
+- Attributes of that object -> fields inside that app
+- Another business object -> a separate app, not a text field
+- Cross-object links -> relation fields, not text fields
+
+- Authentication and workspace: `auth_*`, `workspace_*`
+- File upload: `file_upload_local`
+- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
+- Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
+- Publish and verify: `app_publish_verify`
+
+Note:
+- Do not try to handcraft raw Qingflow schema or internal solution payloads.
+- Do not rely on low-level `view_*`, `workflow_*`, or `qingbi_report_*` write payloads from public builder flows.
+- Public builder work should stay on the resource path: `resolve -> summary read -> plan -> apply -> attach -> publish_verify`.
+- `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` publish by default; pass `publish=false` only when you intentionally want to leave changes in draft.
+- If you are unsure about a public builder tool's keys, aliases, presets, or minimal legal shape, call `builder_tool_contract` instead of guessing.
+- For views, always write the canonical key `columns`. Do not emit `column_names`; treat `fields` only as a tolerated legacy alias, not the preferred shape.
+- For flow presets, map natural language to canonical values before calling MCP:
+  - “默认审批/基础审批/普通审批” -> `basic_approval`
+  - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
+- For workflow assignees, prefer roles over explicit members:
+  - use `role_search` first
+  - use `member_search` only when the user explicitly names members or no stable role exists
+  - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
+- On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
+
+Default policy:
+
+- Creating or updating one app inside an existing package: resolve the package/app, read compact state, plan patches on the server, then apply schema/layout/flow/views patches explicitly.
+- If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
+- If the user describes a system/package with multiple forms or modules, do not start with `app_schema_apply` on the package name. Resolve or create the package first, then create each app separately.
+
+## Standard Operating Order
+
+Before any business tool:
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm whether the task is read-only or write-impacting
+
+For builder work:
+
+1. Resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`. If you believe a new package should be created, ask the user to confirm before calling `package_create`.
+2. Decide whether the target is one app or a multi-app package:
+   - one app: continue with `app_resolve`
+   - multi-app package/system: create or resolve the package, then create each app separately before adding relations
+3. Resolve the target app with `app_resolve` if the request is an update.
+4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
+5. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
+6. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
+7. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
+8. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
+9. Use `app_flow_apply` after schema exists. It publishes by default.
+10. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
+11. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
+12. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
+
+For view work, keep the order strict:
+
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever `app_views_apply` returns `failed` or `partial_success`
+
+For flow work, keep the order strict:
+
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search` if assignees need to come from the directory
+5. `role_create` if the user wants a reusable role and no suitable role exists yet
+6. Start from a canonical preset when possible
+7. Use patch-style edits to that skeleton instead of freehand full-graph generation
+8. When patching a preset skeleton, reuse the preset node ids:
+   - `basic_approval` -> patch `approve_1`
+   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
+   Do not invent a second approval/fill node id unless you are intentionally replacing the skeleton and removing the preset node.
+9. Declare approver/fill/copy assignees explicitly:
+   - prefer `assignees.role_names`
+   - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
+10. When a node must edit specific fields, declare `permissions.editable_fields`
+11. `app_flow_plan`
+12. `app_flow_apply`
+13. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
+
+In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
+
+For additive work on existing systems:
+
+1. Confirm the target package or existing apps
+2. Avoid creating a new package unless the user explicitly wants a separate solution
+3. Use ordinary low-level tools for incremental change
+4. Re-verify the affected apps, views, workflows, or portal after modification
+
+## Safe Usage Rules
+
+- When using `package_name`, expect deterministic resolution only on a unique exact package name match; if multiple packages match, stop and resolve the ambiguity instead of guessing
+- `app_schema_apply` is the only public patch tool allowed to create an app shell; `app_layout_apply`, `app_flow_apply`, and `app_views_apply` require an existing app.
+- Prefer `*_plan` before `*_apply`; the plan tools do server-side normalization and return the next executable call skeleton.
+- For abstract requests like “默认视图”, “基础审批流”, “灵活流程”, or “美观布局”, first translate the intent into a stable preset or explicit patch. Do not send those phrases to MCP unchanged.
+- If the user asks for a business system or package that contains several forms, do not use the system/package name as `app_name` and do not try to store the child app names as text fields.
+- For flexible workflow requests, split the work into two steps:
+  1. create a base skeleton with a preset
+  2. apply explicit business-specific changes as patchable nodes/transitions
+- For preset-based flows, treat preset node ids as part of the public contract. Patch the skeleton nodes by the same ids instead of creating a parallel node with a new id and leaving the preset node unassigned.
+- Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
+- For workflow nodes, use the canonical public shape:
+  - `assignees.role_names`
+  - `assignees.member_names`
+  - `permissions.editable_fields`
+- Reuse `app_flow_plan` output directly when it succeeds. Do not rewrite it into internal keys such as `role_entries` or `editable_que_ids`.
+- Reuse `app_views_plan` output directly when it succeeds. Do not re-expand aliases such as `column_names`.
+- For layout work, keep the public section shape canonical:
+  - `title`
+  - `rows`
+  Do not invent top-level layout `columns`, and do not prefer `fields` or `field_ids` once `rows` is known.
+- Translate natural language like “一行四个字段 / 四列布局 / 每行放四个” into `rows` matrices, not guessed layout parameters.
+- If the same layout-shape `VALIDATION_ERROR` repeats twice, stop guessing and re-read `builder_tool_contract(app_layout_plan)` or the layout reference before trying again.
+- Do not guess role ids or member ids. Resolve them from the directory first.
+- `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
+- `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
+- `relation` and `subtable` must be explicit; do not infer them from vague natural language.
+- Another app is not a field. If two business objects should both have their own records, build two apps and connect them with relation fields.
+- In `prod`, prefer explicit patch tools and avoid any speculative create flow.
+- Never try to bypass collaborative edit locks. `app_release_edit_lock_if_mine` is only for the case where the lock owner is the current authenticated user.
+
+## Response Interpretation
+
+- low-level list totals from the backend may report `0` while rows are present; prefer summary or aggregate readbacks for final conclusions
+- `app_publish_verify` is the publish source of truth.
+- If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
+- Treat post-write readback as the source of truth, not just write status codes
+- For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
+- For views, “view exists” is not the same as “filters are active”. If `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, report the view as created but the filters as unverified until readback confirms them.
+- If multiple views share the same name, do not guess which one to update. Read `view_key` from `app_read_views_summary` and pass it explicitly in `upsert_views[]`.
+- In final user-facing summaries, distinguish clearly between:
+  - contract is visible / canonical shape is known
+  - plan succeeded
+  - apply landed and readback verified it
+  - base template/skeleton applied
+  - business-specific rules completed
+  - remaining gaps or follow-up patches
+- Do not report “流程已满足业务需求” when only a preset skeleton has landed.
+
+## Practical Patterns
+
+- List packages: `package_list`
+- Resolve one package: `package_resolve`
+- Create one package: `package_create`
+- Read one public tool contract: `builder_tool_contract`
+- Resolve one app: `app_resolve`
+- Read one app summary: `app_read_summary`
+- Read fields only: `app_read_fields`
+- Read layout summary: `app_read_layout_summary`
+- Read views summary: `app_read_views_summary`
+- Read flow summary: `app_read_flow_summary`
+- Plan schema patch: `app_schema_plan`
+- Plan layout patch: `app_layout_plan`
+- Plan workflow patch: `app_flow_plan`
+- Plan view patch: `app_views_plan`
+- Search members for workflow assignees: `member_search`
+- Search roles for workflow assignees: `role_search`
+- Create reusable workflow role: `role_create`
+- Add/update/remove fields: `app_schema_apply`
+- Merge or replace layout: `app_layout_apply`
+- Replace workflow: `app_flow_apply`
+- Upsert/remove views: `app_views_apply`
+- Attach one app to a package: `package_attach_app`
+- Release your own stale edit lock: `app_release_edit_lock_if_mine`
+- Publish and verify: `app_publish_verify` when you need a separate verification pass beyond the default auto-publish behavior in apply tools
+
+Detailed playbooks:
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
+- Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Create one app in an existing package: [references/create-app.md](references/create-app.md)
+- Update fields only: [references/update-schema.md](references/update-schema.md)
+- Update layout only: [references/update-layout.md](references/update-layout.md)
+- Update workflow only: [references/update-flow.md](references/update-flow.md)
+- Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
+- Update views only: [references/update-views.md](references/update-views.md)
+- Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App Builder"
+  short_description: "Build and modify Qingflow apps and systems"
+  default_prompt: "Use $qingflow-app-builder to build or modify a Qingflow app or system safely, and verify environment routing and post-write readbacks when builder flows touch live data."

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

@@ -0,0 +1,148 @@
+# Create App
+
+Use this when the user wants one new app inside an existing package.
+
+Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
+
+1. resolve or create the package
+2. create each app separately
+3. attach each app to the package
+4. add relation fields between apps
+
+Hierarchy reminder:
+
+- package -> app -> field -> relation
+- another business object is another app, not a text field
+
+If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, call `package_create` before this sequence.
+
+## Minimal sequence
+
+1. `package_resolve`
+2. `app_resolve`
+3. `app_schema_plan`
+4. `app_schema_apply`
+5. `package_attach_app`
+6. `app_publish_verify` only when the user asks for explicit final verification
+
+## Multi-app systems are different
+
+If the user says things like:
+
+- “创建一个完整应用包”
+- “包含项目、需求、任务、缺陷、团队这几个表单”
+- “这些表单之间建立关联关系”
+
+then do not treat that as one app.
+
+Use this pattern instead:
+
+1. `package_resolve` or `package_create`
+2. for each app name, run `app_schema_plan -> app_schema_apply -> package_attach_app`
+3. once the apps exist, add `relation` fields between them
+
+## Example
+
+Create a new package only after the user confirms package creation:
+
+```json
+{
+  "tool_name": "package_create",
+  "arguments": {
+    "profile": "default",
+    "package_name": "研发项目管理"
+  }
+}
+```
+
+Resolve the package:
+
+```json
+{
+  "tool_name": "package_resolve",
+  "arguments": {
+    "profile": "default",
+    "package_name": "测试应用包"
+  }
+}
+```
+
+Plan schema for a new app:
+
+```json
+{
+  "tool_name": "app_schema_plan",
+  "arguments": {
+    "profile": "default",
+    "app_name": "客户订单",
+    "package_tag_id": 1218950,
+    "create_if_missing": true,
+    "add_fields": [
+      {"name": "订单编号", "type": "text", "required": true},
+      {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单金额", "type": "amount"},
+      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+    ],
+    "update_fields": [],
+    "remove_fields": []
+  }
+}
+```
+
+Apply schema. This publishes by default:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_name": "客户订单",
+    "package_tag_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "add_fields": [
+      {"name": "订单编号", "type": "text", "required": true},
+      {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单金额", "type": "amount"},
+      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+    ],
+    "update_fields": [],
+    "remove_fields": []
+  }
+}
+```
+
+Attach explicitly if `tag_ids_after` does not yet contain the package:
+
+```json
+{
+  "tool_name": "package_attach_app",
+  "arguments": {
+    "profile": "default",
+    "tag_id": 1218950,
+    "app_key": "APP_KEY_FROM_SCHEMA_APPLY"
+  }
+}
+```
+
+## Common failures
+
+### `APP_NOT_FOUND`
+
+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`.
+
+### `PACKAGE_ATTACH_FAILED`
+
+Do not retry schema creation. Re-run only `package_attach_app`, then verify with `app_read_summary`.
+
+### Hierarchy modeling mistake
+
+If the user asked for several named forms/apps but the draft patch turns them into text fields inside one app, stop and remodel the task as:
+
+- one package
+- many apps
+- relation fields between those apps

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

@@ -0,0 +1,63 @@
+# Environment Switching
+
+Use this reference before any builder-side write, repair, or verification flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: build validation, mock data, trial package creation, safe iteration
+- `prod`: formal business system changes in the live environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- first application of a new `SolutionSpec`
+- trying `solution_build_all(..., verify=true)`
+- package initialization and schema evolution experiments
+- mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
+
+Builder behavior in test:
+
+- `preflight` or `plan` is still preferred, but fast `apply` is acceptable when the user explicitly wants an end-to-end smoke test
+- package creation is acceptable
+- verify should read back apps, views, portal, navigation, and sample records
+
+Known current test backend:
+
+- use an explicitly provided non-production backend
+
+## Production Environment
+
+Use production for:
+
+- changes to real business systems
+- additive modifications to live packages and apps
+- controlled rollout of approved solution specs
+
+Builder behavior in prod:
+
+- always identify the target package or app set before changing anything
+- default to `preflight` or `plan` before any `apply`
+- additive requirements should modify the existing package with ordinary tools by default
+- if creating a new package seems necessary in prod, ask the user to confirm package creation first
+- do not seed mock data unless the user explicitly approves it for production
+- verify is mandatory after writes
+
+Production guardrails:
+
+- restate the target workspace and target package before any write
+- call out whether the action creates, mutates, or deletes builder-side configuration
+- if a safer read-only inspection can answer the request, do that first
+
+## Reporting Rule
+
+For builder work, always report:
+
+- active environment
+- target workspace
+- whether the operation is `plan`, `apply`, `repair`, or `verify`
+- whether it touches an existing package or creates a new one