---
name: corezoid-process-tech-writer
description: >
  Documents a Corezoid process — produces a human-readable Markdown file AND enriches
  the process JSON with descriptions on every node and parameter. Output is designed for
  team wikis, internal portals, and future product integration.
  Activate whenever a user asks to document a process, write docs for a connector,
  add descriptions to a process, create documentation for a logic, describe what a
  process does, or any similar phrasing. Also activate when the user shares a process
  JSON and asks to explain it or make it self-documenting. Always produce BOTH outputs
  (Markdown file + enriched JSON) — never just one.
---

# Corezoid Process Tech Writer

Always produce **two outputs** for every process:
1. Markdown documentation file at `.processes/<name>-docs.md`
2. Enriched process JSON (same file, `description` fields filled in) at `.processes/<name>-enriched.json`

---

## Step 0 — Load the process

If the user provides a file path, read it directly. If they provide a process name or ID, use
`pull-process` to fetch it first.

---

## How to extract information from the process JSON

### Inputs
Read the `params` array. Each entry has:
- `name` — parameter name
- `type` — data type
- `descr` — description (may be empty — infer from context)
- `flags` — `"required"` flag means mandatory; `"input"` = input param, `"output"` = output param
- `regex` — validation pattern (document if non-empty)

### Outputs
Find all nodes with `api_rpc_reply` logic in `condition.logics`:
- `throw_exception: false` → success response — document `res_data` keys and types
- `throw_exception: true` → error response — document what triggers it (node title, `exception_reason` if present)

### Process flow
Walk `scheme.nodes` following `go` entries from the Start node (`obj_type: 1`):
- Start → node with `id` matching the `to_node_id` in Start's `go` logic
- Continue following `go` entries to map the happy path
- Note branches at Condition nodes or `go_if_const` entries
- Note error paths via `err_node_id` references

### External dependencies
- API Call nodes (`api` logic): extract `url`, `method`, `extra_headers`
- `{{env_var[@name]}}` references: list all unique variable names used
- Code nodes (`api_code`): look for referenced services or data transformations
- Call Process nodes (`api_rpc`): extract `conv_id` values (called process IDs)

---

## Output 1: Markdown documentation

Save to `.processes/<process-name-in-snake-case>-docs.md`.

Use this exact structure:

```markdown
# <Process Title>

## Overview
<1-2 sentences: what this process does and when to call it. Be specific about the business purpose.>

## Input Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_name | string | Yes | Description from params.descr |
| optional_field | number | No | Description |

<If any field has regex validation, add a "Validation" subsection listing the rules.>

## Output

### Success response
| Field | Type | Description |
|-------|------|-------------|
| response | object | The API response body |

### Error cases
| Error | Trigger condition |
|-------|------------------|
| "Code node error" | JavaScript execution failed in the preparation step |
| "API call error" | External API returned an error or was unreachable |

## How to Call

Example `task_data` with realistic values:
​```json
{
  "field_name": "example_value",
  "optional_field": 42
}
​```

## Process Flow

1. **Start** — Entry point, receives the task
2. **<Code Node title>** — <plain English: what this step does>
3. **<API Call / Call Process title>** — <plain English: what is called and why>
4. **<Reply node title>** — <what is returned on success>
5. **Final** — Task stored, process complete

<For error paths, describe them after the happy path:>

**Error path (Code Node failure):** If the preparation step fails, an error reply is returned
with the exception description, and the task ends at the Error node.

## External Dependencies

| Dependency | Type | Variable / URL |
|-----------|------|----------------|
| <service name> | HTTP API | `{{env_var[@variable-name]}}` |
| <process name> | Corezoid process | ID: `<conv_id>` |

## Notes

- <Any timeouts configured via semaphors — e.g. "API call has a 30-second timeout">
- <Rate limiting (max_threads setting)>
- <Any other relevant technical notes>
```

---

## Output 2: Enriched process JSON

Read the original process JSON, add `description` fields to every node, and write the result
to `.processes/<name>-enriched.json`.

### Rules for node enrichment

**What to fill:**
- `description` field on every node — one plain English sentence: what this node does in the context of this process
- `params[].descr` — if empty, infer from the field name and process context

**What NOT to change:**
- `id`, `obj_type`, `condition`, `logics`, `semaphors` — never touch these
- `x`, `y`, `extra`, `options` — leave as-is
- `title` — only fill if the field is completely empty (`""`)

**Description style:**
- One sentence, active voice, present tense
- Specific to this process — not generic ("Handles errors" is bad; "Returns an error reply if the actor creation API call fails" is good)
- Reference actual data fields and external services where relevant

**Examples:**

| Node type | Bad description | Good description |
|-----------|----------------|-----------------|
| Code node | "Prepares data" | "Builds the request body with actor_name, form_id, and authorization_header for the Simulator API call" |
| API Call | "Makes API call" | "Sends POST request to Simulator API to create a new actor with the prepared parameters" |
| Reply Success | "Returns response" | "Returns the created actor data from the Simulator API back to the calling process" |
| Reply Error | "Returns error" | "Returns error reply with throw_exception:true when the actor creation API call fails" |
| Final | "Final" | "Stores the completed task with actor creation result and marks the process as successful" |

---

## Both files must be produced in the same response

Do not produce one without the other. If the process JSON is very large, produce the Markdown
first, then the enriched JSON.