Update to Corezoid

{
  "description": "Manages Corezoid environment variables (env_var) — create, list, modify, delete, and use variables in process JSON. Activate when the user mentions \"variable\", \"env var\", \"environment variable\", \"secret\", \"create variable\", \"list variables\", \"delete variable\", \"modify variable\", \"env_var\", \"{{env_var\", or asks how to store a URL, token, API key, or any constant that should not be hardcoded in a process. Also activate when a process references {{env_var[@name]}} and the variable does not exist yet.\n",
  "included_files": [],
  "name": "corezoid-variable-manager",
  "skill_md_contents": "---\nname: corezoid-variable-manager\ndescription: >\n  Manages Corezoid environment variables (env_var) — create, list, modify, delete, and\n  use variables in process JSON. Activate when the user mentions \"variable\", \"env var\",\n  \"environment variable\", \"secret\", \"create variable\", \"list variables\", \"delete variable\",\n  \"modify variable\", \"env_var\", \"{{env_var\", or asks how to store a URL, token, API key,\n  or any constant that should not be hardcoded in a process. Also activate when a process\n  references {{env_var[@name]}} and the variable does not exist yet.\n---\n\n# Corezoid Variable Manager\n\n## How to call these tools\n\nEvery operation in this skill is an **action of the single `cz-variables` MCP tool** —\nthe individual names below are action strings, not tools of their own:\n\n```\ncz-variables {\"action\": \"list-variables\"}\n```\n\nArguments always go inside `args`; the shorthand used in the examples below — `create-variable(name=\"payment-api-url\", …)` — means exactly that call. When unsure about an action's\narguments, call `cz-variables {\"action\": \"<action>\", \"help\": true}` — it returns the\nfull schema and runs nothing.\n\n## What variables are\n\nEnvironment variables store constants (URLs, tokens, API keys, IDs, configuration values)\nthat must not be hardcoded in process logic. The reference syntax `{{env_var[@name]}}` is\nresolved at runtime — changing a variable value takes effect immediately without\nredeploying any process.\n\nVariables are **stage-scoped**: shared across all processes within a stage.\n\n---\n\n## Variable types\n\n### By data type\n\n| `data_type` | When to use | Value format |\n|-------------|-------------|--------------|\n| `raw` | Plain string (URL, token, ID, any scalar) | `\"https://api.example.com\"` |\n| `json` | Structured config, multi-field config, feature flags | `{\"key\":\"value\",\"nested\":{...}}` |\n\n### By visibility\n\n| `env_var_type` | UI display | Accessible from | Scopes |\n|----------------|------------|-----------------|--------|\n| `visible` | Value shown in plain text | All node types | `[{\"type\":\"*\",\"fields\":\"*\"}]` |\n| `secret` | Value masked, shows only fingerprint | API Call nodes only | `[{\"type\":\"api_call\",\"fields\":\"*\"}]` |\n\n> ⚠️ **Secret variables** are designed for tokens, passwords, and API keys. They are\n> never returned in plain text by the API after creation — only an MD5/SHA256 fingerprint\n> is available. Use `visible` for non-sensitive configuration.\n\n---\n\n## Actions of `cz-variables`\n\n| Action | Purpose |\n|--------|---------|\n| `create-variable` | Create a `raw` + `visible` variable in one step |\n| `list-variables` | List a stage's variables with obj_id, types, values (secrets masked) |\n| `modify-variable` | Change value/title/data_type or rename — dry-run + confirm-gated |\n| `delete-variable` | PERMANENTLY delete (no recycle bin) — dry-run + confirm-gated |\n\n> **Note:** creating `secret` or `json` variables is not yet exposed as an action —\n> use the direct API calls documented below for creation; manage them afterwards with\n> the actions above.\n\n## Double-confirmation etiquette (modify / delete)\n\n`modify-variable` and `delete-variable` are consequential: a deleted variable is gone\nFOREVER (env vars have NO recycle bin), a renamed one breaks every\n`{{env_var[@old-name]}}` reference, and a changed value takes effect immediately in\nrunning processes. The actions enforce a two-step gate, and you must drive it honestly:\n\n1. Call the action WITHOUT `apply` — you get a dry-run: a current → new diff (modify) or\n   a red `🔴 PERMANENT DELETION` block (delete), including a local reference scan.\n2. Show that dry-run output to the user **verbatim** — do not summarize away the\n   warnings, especially the red block and the list of files that still reference the\n   variable.\n3. Ask the user explicitly whether to proceed, and wait for their clear agreement in\n   the conversation.\n4. Only then re-run with `apply=true` and the exact `confirm=\"<short_name>#<obj_id>\"`\n   from the dry-run output. Never fabricate the confirm string without steps 1–3, and\n   never treat an earlier, unrelated \"yes\" as agreement for this action.\n\nServer facts the tools rely on (verified live): modify is PARTIAL — omitted fields\nkeep their value, so modifying a secret's title does not require (or touch) its value;\n`env_var_type` (visible/secret) can NOT be changed after creation — the server\nsilently ignores such attempts; delete requires project_id + stage_id and is\nirreversible.\n\n---\n\n## Using variables in process JSON\n\nOnce a variable exists, reference it with `{{env_var[@short-name]}}` anywhere a value\nis expected.\n\n### API Call node — URL field\n```json\n{\n  \"type\": \"api\",\n  \"url\": \"{{env_var[@payment-api-url]}}/charge\",\n  \"method\": \"POST\",\n  \"extra_headers\": {},\n  \"max_threads\": 5,\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### API Call node — header field\n```json\n{\n  \"type\": \"api\",\n  \"url\": \"{{env_var[@payment-api-url]}}/charge\",\n  \"method\": \"POST\",\n  \"extra_headers\": {},\n  \"max_threads\": 5,\n  \"extra\": { \"Authorization\": \"Bearer {{env_var[@payment-api-token]}}\" },\n  \"extra_type\": { \"Authorization\": \"string\" },\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### Set Parameters node\n```json\n{\n  \"type\": \"set_param\",\n  \"extra\": {\n    \"baseUrl\": \"{{env_var[@service-url]}}\",\n    \"token\":   \"{{env_var[@service-token]}}\"\n  },\n  \"extra_type\": {\n    \"baseUrl\": \"string\",\n    \"token\":   \"string\"\n  },\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### Call a Process node — passing variable as parameter\n```json\n{\n  \"type\": \"api_rpc\",\n  \"conv_id\": \"@target-process\",\n  \"extra\": { \"endpoint\": \"{{env_var[@service-endpoint]}}\" },\n  \"extra_type\": { \"endpoint\": \"string\" },\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### Condition node (`go_if_const`)\n\nVariable references work in condition expressions as both the left-hand value and the\ncomparison value:\n\n```json\n{\n  \"type\": \"go_if_const\",\n  \"conditions\": [\n    {\n      \"fun\": \"equal\",\n      \"arg\": \"{{env_var[@feature-flag]}}\",\n      \"val\": \"enabled\"\n    }\n  ],\n  \"to_node_id\": \"<next_node_id>\"\n}\n```\n\n### Code node — variables must be pre-loaded via set_param\nVariables are not directly accessible inside `api_code` JavaScript. First assign them\nto task fields using a `set_param` node upstream, then read via `data.*` in code:\n```javascript\n// In set_param upstream: \"apiUrl\": \"{{env_var[@my-api-url]}}\"\nvar url = data.apiUrl + \"/endpoint\";\n```\n\n---\n\n## Naming rules\n\n- Only lowercase letters `[a-z]`, digits `[0-9]`, and hyphens `-`\n- Name and description must be **at least 3 characters**\n- Must be unique within the stage\n- Good: `stripe-secret-key`, `payment-api-url`, `db-host-prod`\n- Bad: `URL`, `TOKEN`, `x`, `My_Var`\n\n---\n\n## Local cache files\n\nTwo files store variable information locally. Check **both** before creating a new variable:\n\n| File | Created by | Contains |\n|------|------------|---------|\n| `_ENV_VARS_.json` | `pull-folder` (ZIP export from Corezoid) | All variables in the stage |\n| `.processes/variables.json` | the `create-variable` action | Only variables created in this session |\n\nIf neither file exists, run `pull-folder` or call the list API (see below) to get the\ncurrent state.\n\n---\n\n## Workflow: Create a visible raw variable (MCP tool)\n\n### Step 1 — Check if variable already exists\n\nRead `_ENV_VARS_.json` (or `.processes/variables.json`) and search for the `short_name`.\nIf found, reuse it — do not create a duplicate.\n\n### Step 2 — Create the variable\n\nCall **`cz-variables`** with `action: \"create-variable\"` and these `args`:\n- `name`: the `short_name` (kebab-case, e.g. `stripe-api-key`)\n- `description`: human-readable label (min 3 chars), used as `title` in the API\n- `value`: the actual value\n\n```\ncz-variables {\"action\": \"create-variable\", \"args\": {\n  \"name\": \"payment-api-url\",\n  \"description\": \"Payment Service Base URL\",\n  \"value\": \"https://api.payments.example.com\"\n}}\n```\n\nThe action creates the variable in Corezoid and appends it to `.processes/variables.json`.\n\n### Step 3 — Reference in process JSON\n\nUse `{{env_var[@payment-api-url]}}` wherever this value is needed.\n\n---\n\n## Workflow: Create a secret variable (direct API)\n\nUse when storing tokens, passwords, API keys — values that must be masked in the UI.\n\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\":         \"create\",\n    \"obj\":          \"env_var\",\n    \"obj_type\":     0,\n    \"status\":       \"active\",\n    \"data_type\":    \"raw\",\n    \"env_var_type\": \"secret\",\n    \"title\":        \"Stripe Secret Key\",\n    \"short_name\":   \"stripe-secret-key\",\n    \"description\":  \"\",\n    \"value\":        \"sk_live_...\",\n    \"company_id\":   \"<WORKSPACE_ID>\",\n    \"project_id\":   <PROJECT_ID>,\n    \"stage_id\":     <STAGE_ID>,\n    \"scopes\":       [{\"type\": \"api_call\", \"fields\": \"*\"}]\n  }]\n}\n```\n\nResponse: `{ \"obj_id\": 2192, \"proc\": \"ok\", \"fingerprints\": [...] }`\n\n> The value is never returned after creation. Store it securely before calling this API.\n\n---\n\n## Workflow: Create a JSON variable (direct API)\n\nUse when a variable holds a structured config object or array.\n\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\":         \"create\",\n    \"obj\":          \"env_var\",\n    \"obj_type\":     0,\n    \"status\":       \"active\",\n    \"data_type\":    \"json\",\n    \"env_var_type\": \"visible\",\n    \"title\":        \"Service Config\",\n    \"short_name\":   \"service-config\",\n    \"description\":  \"\",\n    \"value\":        \"{\\\"host\\\":\\\"db.example.com\\\",\\\"port\\\":5432,\\\"name\\\":\\\"prod\\\"}\",\n    \"company_id\":   \"<WORKSPACE_ID>\",\n    \"project_id\":   <PROJECT_ID>,\n    \"stage_id\":     <STAGE_ID>,\n    \"scopes\":       [{\"type\": \"*\", \"fields\": \"*\"}]\n  }]\n}\n```\n\n> The `value` field must be a **JSON string** (the JSON content encoded as a string).\n> A secret JSON variable uses `\"env_var_type\": \"secret\"` and\n> `\"scopes\": [{\"type\": \"api_call\", \"fields\": \"*\"}]`.\n\n---\n\n## Workflow: List variables (direct API)\n\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\":       \"list\",\n    \"obj\":        \"env_var\",\n    \"sort\":       \"date\",\n    \"order\":      \"asc\",\n    \"id\":         \"<WORKSPACE_ID>\",\n    \"company_id\": \"<WORKSPACE_ID>\",\n    \"project_id\": <PROJECT_ID>,\n    \"stage_id\":   <STAGE_ID>\n  }]\n}\n```\n\n**Response fields per variable:**\n\n| Field | Description |\n|-------|-------------|\n| `obj_id` | Numeric ID (needed for modify/delete) |\n| `short_name` | The `@name` used in `{{env_var[@name]}}` |\n| `title` | Human-readable display label |\n| `data_type` | `raw` or `json` |\n| `env_var_type` | `visible` or `secret` |\n| `value` | Actual value (empty for `secret` after creation) |\n| `fingerprints` | MD5 + SHA256 hashes — use to detect value changes |\n| `scopes` | Access scope rules |\n| `create_time` / `change_time` | Unix timestamps |\n| `uuid` | Variable UUID |\n\n---\n\n## Workflow: Modify a variable (direct API)\n\nModify updates all mutable fields in one call. Always send the full payload — partial\nupdates are not supported.\n\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\":         \"modify\",\n    \"obj\":          \"env_var\",\n    \"obj_id\":       <VAR_OBJ_ID>,\n    \"data_type\":    \"raw\",\n    \"env_var_type\": \"visible\",\n    \"title\":        \"Updated Display Title\",\n    \"short_name\":   \"new-short-name\",\n    \"description\":  \"\",\n    \"value\":        \"new-value\",\n    \"company_id\":   \"<WORKSPACE_ID>\",\n    \"project_id\":   <PROJECT_ID>,\n    \"stage_id\":     <STAGE_ID>,\n    \"scopes\":       [{\"type\": \"*\", \"fields\": \"*\"}]\n  }]\n}\n```\n\n> ⚠️ Changing `short_name` invalidates all `{{env_var[@old-name]}}` references across\n> every process in the stage. After renaming, grep all `.conv.json` files for the old\n> name and update them, then `push-process` each affected file.\n\n---\n\n## Workflow: Delete a variable (direct API)\n\n> ⚠️ Before deleting, verify no process references `{{env_var[@short-name]}}`.\n> `push-process` validates env_var references and will fail if the variable is missing.\n\n```bash\n# Check which processes reference this variable\ngrep -r \"env_var\\[@variable-name\\]\" . --include=\"*.conv.json\"\n```\n\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\":       \"delete\",\n    \"obj\":        \"env_var\",\n    \"obj_id\":     <VAR_OBJ_ID>,\n    \"company_id\": \"<WORKSPACE_ID>\",\n    \"project_id\": <PROJECT_ID>,\n    \"stage_id\":   <STAGE_ID>\n  }]\n}\n```\n\n---\n\n## Resolving environment values\n\nWhen calling the `create-variable` / `modify-variable` / `delete-variable` / `list-variables` actions you do **not** need to look up `stage_id` or `project_id` — MCP resolves both from the `<id>_<name>.stage.json` marker at the workspace root.\n\nFor **direct** `/api/2/json` calls (the raw workflows below) you need the values explicitly:\n\n| Value | Where to find it |\n|-------|------------------|\n| `company_id` | `workspace_id` field in current Folder in `~/.corezoid/config.json` |\n| `stage_id` | `obj_id` in `<id>_<name>.stage.json` at the workspace root |\n| `project_id` | `parent_id` in the same `<id>_<name>.stage.json` |\n| API URL | `corezoid_url` field in current Folder |\n| Access token | `access_token` field in current Folder |\n| `obj_id` of variable | List API response, or `_ENV_VARS_.json` |\n\nIf the marker file is missing, run the `corezoid-init` skill.\n\n---\n\n## Runtime behaviour\n\n- Variables are resolved **before** the node executes — the `{{env_var[@name]}}` token\n  is replaced with the live value at the moment the task reaches that node\n- Updating a variable value takes effect **immediately** — no process redeploy needed\n- `push-process` validates all `{{env_var[@name]}}` references: if the variable does not\n  exist in the stage, deployment fails with an error\n\n---\n\n## Common pitfalls\n\n| Mistake | Correct approach |\n|---------|-----------------|\n| `{{env_var[payment-url]}}` — missing `@` | `{{env_var[@payment-url]}}` — `@` is required |\n| `{{env_var[@Payment-URL]}}` — uppercase | `{{env_var[@payment-url]}}` — always lowercase |\n| Storing secrets as `visible` variables | Use `env_var_type: \"secret\"` for tokens and passwords |\n| Trying to read a `secret` variable in a Code node | Secret variables are only accessible from `api` (API Call) nodes |\n| Duplicate variable creation | Always read `_ENV_VARS_.json` or call the list API first |\n| Renaming `short_name` without updating process files | Grep all `.conv.json`, update references, push each changed process |\n| Deleting a variable used by active processes | `push-process` will fail; remove all references first |\n| Passing large JSON config as raw string | Use `data_type: json` for structured values |\n\n---\n\n## Reference Documents\n\n| Path | When to read |\n|------|-------------|\n| `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md` | Naming rules and usage examples (quick reference) |\n| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/set-parameters-node.md` | How `set_param` feeds variables into task data for Code nodes |\n| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/api-call-node.md` | How variables are used in URL, headers, and body fields |\n| `${CLAUDE_PLUGIN_ROOT}/docs/process/process-json-validation.md` | How `push-process` validates `{{env_var[@name]}}` references |\n"
}