{"id":29516,"plugin_id":"plugin_asdk_app_6ac4c3b919f48191a49821b96bdc33a2","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-09T00:04:18.360Z","digest":"2dd876a1740128361eb4d2b8b985e8c0d0c9fa76fe78fd314cc8e9f708ff4785","against":null,"payload":{"description":"Manages Corezoid aliases — create, list, modify, delete, link/unlink, and use aliases in process JSON. Activate when the user mentions \"alias\", \"short_name\", \"short name\", \"create alias\", \"list aliases\", \"delete alias\", \"modify alias\", \"rename alias\", \"unlink alias\", \"link alias\", \"get callback hash\", \"conv[@\", or asks how to reference a process by name instead of numeric ID. Also activate when reviewing a process that uses numeric conv_id values and the user wants to replace them with aliases.\n","included_files":[],"name":"corezoid-alias-manager","skill_md_contents":"---\nname: corezoid-alias-manager\ndescription: >\n  Manages Corezoid aliases — create, list, modify, delete, link/unlink, and use aliases\n  in process JSON. Activate when the user mentions \"alias\", \"short_name\", \"short name\",\n  \"create alias\", \"list aliases\", \"delete alias\", \"modify alias\", \"rename alias\",\n  \"unlink alias\", \"link alias\", \"get callback hash\", \"conv[@\", or asks how to reference\n  a process by name instead of numeric ID. Also activate when reviewing a process that\n  uses numeric conv_id values and the user wants to replace them with aliases.\n---\n\n# Corezoid Alias Manager\n\n## What aliases are\n\nAn alias is a human-readable `short_name` (e.g. `payment-service`, `send-otp`) that\nmaps to a process (`conv`). Aliases serve two purposes:\n\n1. **Process reference in JSON** — use `@alias-name` as `conv_id` instead of a numeric\n   process ID. This makes processes portable across environments and removes hardcoded IDs.\n2. **External HTTP entry point** — each alias generates a `callback_hash` used to send\n   tasks to the process via the API Gateway URL.\n\nAlias naming rules (same as Corezoid short names):\n- Only lowercase letters `[a-z]`, digits `[0-9]`, and hyphens `-`\n- Must be at least 3 characters\n- Must be unique within the stage\n- Good: `payment-checkout`, `send-otp`, `create-user-v2`\n- Bad: `MyAlias`, `PAYMENT`, `a`\n\n---\n\n## MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `create-alias` | Create an alias and link it to a process in one step |\n| `cz-structure` `list-aliases` | List the aliases of a project's stage (short_name → target conv_id); pass `short_name` to resolve one exact alias instead of scanning the table |\n\n> **Note:** `modify`, `delete`, and `unlink` operations are not yet exposed as\n> MCP tools. Use the direct API calls documented below to perform them.\n\n---\n\n## Using aliases in process JSON\n\nOnce an alias exists, replace the numeric `conv_id` with `@alias-name` in any node that\ncalls another process:\n\n### Call a Process node (`api_rpc`)\n```json\n{\n  \"type\": \"api_rpc\",\n  \"conv_id\": \"@payment-checkout\",\n  \"extra\": { \"amount\": \"{{amount}}\", \"currency\": \"{{currency}}\" },\n  \"extra_type\": { \"amount\": \"number\", \"currency\": \"string\" },\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### Copy Task node (`api_copy`)\n```json\n{\n  \"type\": \"api_copy\",\n  \"conv_id\": \"@send-notification\",\n  \"ref\": \"{{unique_ref}}\",\n  \"mode\": \"create\",\n  \"err_node_id\": \"<error_node_id>\"\n}\n```\n\n### State store read in `set_param` or condition\n```\n{{conv[@user-states].ref[{{task_ref}}].status}}\n```\n\nThis reads the `status` field of the task with reference `{{task_ref}}` from the\n`@user-states` state diagram process.\n\n---\n\n## Workflow: Create an alias\n\n### Step 1 — Resolve the process\n\nCheck whether the user provided a file path, process name, or process ID.\nIf a file path is given, the process ID is the leading number in the filename\n(e.g. `1834583_My_Process.conv.json` → `process_id = 1834583`).\n\nIf only a name is given, search locally:\n```bash\nfind . -name \"*.conv.json\" | xargs grep -l '\"title\": \"My Process\"'\n```\n\n### Step 2 — Check if the alias already exists\n\nBefore creating, verify the `short_name` is not taken. Call the list aliases API\n(see \"Workflow: List aliases\" below) and scan the `short_name` fields.\nIf a conflict is found, suggest an alternative name to the user.\n\n### Step 3 — Decide the short_name\n\nApply the naming rules: lowercase, hyphens, no spaces or underscores, at least 3 chars.\nSuggest a name derived from the process title if the user hasn't specified one.\n\n### Step 4 — Create the alias\n\nCall MCP tool **`create-alias`** with:\n- `process_path`: relative path to the `.conv.json` file\n- `short_name`: the alias short name\n\n```\ncreate-alias(\n  process_path=\"./671255_develop/1834583_My_Process.conv.json\",\n  short_name=\"payment-checkout\"\n)\n```\n\nThe tool creates the alias, links it to the process, and returns the `alias_id`.\nRequires a `<id>_<name>.stage.json` marker at the workspace root (run `corezoid-init` if missing).\n\n### Step 5 — Update and redeploy referencing processes\n\nAfter creating the alias, replace any numeric `conv_id` references to this process\nacross the project with `@short-name`:\n\n```bash\ngrep -rl '\"conv_id\": 1834583' . --include=\"*.conv.json\"\n```\n\nFor each file found, replace `\"conv_id\": 1834583` with `\"conv_id\": \"@payment-checkout\"`.\nThen for each modified file, run **`lint-process`** and on success **`push-process`**.\n\n> After pushing, tell the user: \"Changes deployed. Please **refresh the page** in Corezoid to see the updated process.\"\n\n---\n\n## Workflow: List aliases\n\nCall `cz-structure` with action `list-aliases`:\n\n```\ncz-structure {\"action\": \"list-aliases\", \"args\": {\n  \"company_id\": \"<WORKSPACE_ID>\",\n  \"project_id\": <PROJECT_ID>,\n  \"stage_id\": <STAGE_ID>,\n  \"short_name\": \"<optional: filter to one exact alias>\"\n}}\n```\n\n`company_id`, `project_id` and `stage_id` identify the project/stage to search — resolve\nthem with `list-projects`/`list-stages` (`cz-structure`) when searching a stage other than\nthe one currently configured. Pass `short_name` when you already know the alias you need\n(e.g. resolving a receiver by name) to get a one-line answer instead of the full table.\n\n**Returned per alias:**\n| Field | Description |\n|-------|-------------|\n| Alias ID | Numeric ID (needed for modify/delete/link via the raw API — see below) |\n| Title | Human-readable display title |\n| Short name | The `@short-name` used in `conv_id` references |\n| Target conv_id | Process (`conv`) ID this alias points to |\n\n---\n\n## Workflow: Modify an alias\n\nTo rename an alias or change its title/description (does NOT change which process it\npoints to — use unlink + link for that).\n\n**API call:**\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\": \"modify\",\n    \"obj\": \"alias\",\n    \"obj_id\": <ALIAS_ID>,\n    \"title\": \"New Display Title\",\n    \"short_name\": \"new-short-name\",\n    \"description\": \"Updated description\",\n    \"company_id\": \"<WORKSPACE_ID>\",\n    \"project_id\": <PROJECT_ID>,\n    \"stage_id\": <STAGE_ID>\n  }]\n}\n```\n\n> ⚠️ Changing `short_name` invalidates all `\"conv_id\": \"@old-name\"` references\n> across every process in the project. Grep all `.conv.json` files and update them,\n> then push each modified process.\n\n---\n\n## Workflow: Repoint an alias to a different process\n\nUse two API calls: unlink from the current process, then link to the new one.\n\n### Step 1 — Unlink from current process\n```\nPOST {corezoid_url}/api/2/json\n\n{\n  \"ops\": [{\n    \"type\": \"link\",\n    \"obj\": \"alias\",\n    \"link\": false,\n    \"obj_id\": <ALIAS_ID>,\n    \"obj_to_id\": <CURRENT_PROCESS_ID>,\n    \"obj_to_type\": \"conv\",\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\n### Step 2 — Link to new process\n```\nPOST {corezoid_url}/api/2/json\n\n{\n  \"ops\": [{\n    \"type\": \"link\",\n    \"obj\": \"alias\",\n    \"link\": true,\n    \"obj_id\": <ALIAS_ID>,\n    \"obj_to_id\": <NEW_PROCESS_ID>,\n    \"obj_to_type\": \"conv\",\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\n---\n\n## Workflow: Delete an alias\n\n> ⚠️ Before deleting, check all `.conv.json` files for `\"conv_id\": \"@alias-name\"` references.\n> Deleting an alias breaks every process that uses it.\n\n**API call:**\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\": \"delete\",\n    \"obj\": \"alias\",\n    \"obj_id\": <ALIAS_ID>,\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\nAfter deletion, replace all `\"conv_id\": \"@alias-name\"` references with the numeric\nprocess ID (or create a new alias), then push each affected process.\n\n---\n\n## Workflow: Get callback hash (external task submission URL / Direct URL webhook)\n\nThe callback hash is the secret in a process's or alias's **Direct URL** — the public\nwebhook endpoint external systems POST tasks to. A process and each of its aliases\nhave **independent** hashes; rotating or deleting one does not affect the others.\n\n**Get the hash — by process (`conv_id`):**\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\": \"get\",\n    \"obj\": \"callback_hash\",\n    \"conv_id\": <PROCESS_ID>,\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\n**Get the hash — by alias (`alias_id`):**\n```\nPOST {corezoid_url}/api/2/json\nAuthorization: Simulator {access_token}\nContent-Type: application/json\n\n{\n  \"ops\": [{\n    \"type\": \"get\",\n    \"obj\": \"callback_hash\",\n    \"obj_type\": \"alias\",\n    \"alias_id\": <ALIAS_ID>,\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\n**Response (both):**\n```json\n{ \"request_proc\": \"ok\", \"ops\": [{ \"proc\": \"ok\", \"callback_hash\": \"19e339a865d676db68b776f440443821c49a0e30\" }] }\n```\n\nOther `type` values on the same `obj: \"callback_hash\"` (swap `\"type\": \"get\"` for one of\nthese, keeping the same `conv_id`/`alias_id` field):\n\n| `type` | Effect |\n|---|---|\n| `create` | Enables the Direct URL and issues the first hash |\n| `get` | Returns the current hash without changing anything |\n| `modify` | **Rotates** the hash — the previous URL stops working immediately |\n| `delete` | Disables the Direct URL entirely |\n\n**External submission URL:**\n\n⚠️ The URL format is **installation-specific** — always verify against the Direct URL\nshown in the Corezoid UI for that process/alias before handing it to another system.\nTwo formats have been observed:\n\n- **Cloud (dedicated API Gateway):**\n  ```\n  POST {COREZOID_APIGW_URL}/api/1/json/<WORKSPACE_ID>/<callback_hash>\n  Content-Type: application/json\n\n  { \"ops\": [{ \"ref\": \"unique-task-ref\", \"type\": \"create\", \"obj\": \"task\", \"data\": { \"key\": \"value\" } }] }\n  ```\n  Where `COREZOID_APIGW_URL` defaults to `https://api-apigw.corezoid.com`.\n\n- **Self-hosted (served off the same account host, no separate gateway):**\n  ```\n  By conv_id:  https://<host>/api/2/json/public/<conv_id>/<callback_hash>\n  By alias:    https://<host>/api/2/json/public/@<alias_short_name>/<project_short_name>/<stage_short_name>/<company_id>/<callback_hash>\n  ```\n  `<host>` is the same host as `corezoid_url` on the current Folder. Some installations serve this under\n  `/api/1/json/public/...` instead of `/api/2/` — don't assume without confirming once\n  per installation.\n\nEither way, the hash in the URL **is** the authentication — treat it like a secret.\nPrefer alias-based URLs for anything referenced by external systems: an alias can be\nre-pointed at a new process without invalidating URLs already handed out.\n\n---\n\n## Resolving environment values\n\n`create-alias` resolves `stage_id`/`project_id` automatically from the target process's own\nlocation — no argument needed. `list-aliases` (`cz-structure`) does not: it takes\n`project_id`/`stage_id`/`company_id` explicitly, because it is meant to look up aliases in\nany stage, not only the one currently configured. For **direct** `/api/2/json` calls (the raw\nworkflows above) collect the values from:\n\n| Value | Where to find it |\n|-------|------------------|\n| `company_id` | `workspace_id` field in current Folder (`~/.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\nIf the marker file is missing, run the `corezoid-init` skill.\n\n---\n\n## Two-step create (alternative manual flow)\n\nThe `create-alias` MCP tool creates and links in a single request. If you need\nfiner control (create first, link later), use the two-step API flow:\n\n### Step 1 — Create the alias object\n```json\n{\n  \"ops\": [{\n    \"type\": \"create\",\n    \"obj\": \"alias\",\n    \"title\": \"My Alias Title\",\n    \"short_name\": \"my-alias\",\n    \"description\": \"\",\n    \"company_id\": \"<WORKSPACE_ID>\",\n    \"project_id\": <PROJECT_ID>,\n    \"stage_id\": <STAGE_ID>\n  }]\n}\n```\nResponse: `{ \"obj_id\": <ALIAS_ID>, \"proc\": \"ok\" }`\n\n### Step 2 — Link the alias to a process\n```json\n{\n  \"ops\": [{\n    \"type\": \"link\",\n    \"obj\": \"alias\",\n    \"link\": true,\n    \"obj_id\": <ALIAS_ID>,\n    \"obj_to_id\": <PROCESS_ID>,\n    \"obj_to_type\": \"conv\",\n    \"company_id\": \"<WORKSPACE_ID>\"\n  }]\n}\n```\n\n---\n\n## Common pitfalls\n\n| Mistake | Correct approach |\n|---------|-----------------|\n| `\"conv_id\": \"@My-Alias\"` (uppercase) | `\"conv_id\": \"@my-alias\"` — always lowercase |\n| Deleting an alias without updating referencing processes | Search all `.conv.json` first with `grep -r \"@alias-name\"` |\n| Renaming `short_name` without updating process JSON | Same — grep, replace, push each changed process |\n| Creating an alias with `short_name` that already exists | Use `list aliases` API call first to check |\n| Forgetting to push processes after replacing numeric IDs with aliases | Always `lint-process` then `push-process` for every modified file |\n| Using alias when the workspace has no `<id>_<name>.stage.json` marker | Run `corezoid-init` |\n\n---\n\n## Decision guide\n\n| Situation | Action |\n|-----------|--------|\n| Process has numeric `conv_id` references from other processes | Create alias, then replace all numeric IDs |\n| Setting up a new process that others will call | Create alias at creation time, use `@alias` from the start |\n| Want to swap which process an alias points to (blue/green deploy) | Unlink + Link (keep the `short_name`, update the target) |\n| Decommissioning a process | Check alias references, delete alias, update or deprecate callers |\n| External system needs to send tasks to a process | Get callback hash for the alias, build API Gateway URL |\n| Reviewing a process for hardcoded numeric `conv_id` | Flag each one, suggest alias creation and replacement |\n\n---\n\n## Reference Documents\n\n| Path | When to read |\n|------|-------------|\n| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/call-process-node.md` | `api_rpc` node — where `conv_id: \"@alias\"` is used |\n| `${CLAUDE_PLUGIN_ROOT}/docs/node-structures.md` | JSON schemas for `api_rpc` and `api_copy` (both use `conv_id`) |\n| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/set-parameters-dynamic-values.md` | `{{conv[@alias].ref[...].field}}` state store read pattern |\n| `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md` | Variable naming rules (same convention as alias short names) |\n| `${CLAUDE_PLUGIN_ROOT}/skills/corezoid-review/SKILL.md` | Step 10: External Dependencies — alias audit and creation |\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}