@wowok/agent-mcp 2.2.13 → 2.2.14

package/docs/docs/progress.md

@@ -1,1748 +0,0 @@
-# Progress Component (🔄 Workflow Execution)
-
----
-
-## Component Overview
-
-Progress is WoWok's workflow execution component, used to execute workflow instances created by Machine. Progress tracks the execution status of workflows, manages node transitions, and records execution history.
-
-> **Relationship with Machine**: Progress is an instance of a Machine workflow template. Before creating a Progress:
-> 1. Create and configure a Machine with nodes and forwards
-> 2. **Ensure first node has init connection**: The first node must have `prev_node: ""` to allow Progress to start from the init node
-> 3. Publish the Machine (required before Progress creation)
-> 4. Grant permissions to operators (permissionIndex or namedOperator)
-> 5. Then create Progress from the Machine
->
-> **Understanding Init Node**: When a Progress is created, its `current` field is set to `""` (empty string), representing the init node. To advance to the first actual node, the Machine must define a forward with `prev_node: ""`. See [Machine Component](machine.md) for details on init node configuration.
-
-### Permission Requirements for Progress Operations
-
-To execute a forward operation in Progress, the operator must have the required permission as defined in the Machine node:
-
-**If the forward uses `permissionIndex`:**
-- The operator must be granted that permission index in the Machine's Permission object
-- Grant permission using the `permission` operation with `table.op: "add perm by entity"`
-- Valid permissionIndex values: 1000-65535 (user-defined) or appropriate built-in permissions (100-450+)
-- **Note**: Machine management permissions (200-208) and Progress management permissions (220-225) are NOT valid for forward operations
-
-**If the forward uses `namedOperator`:**
-- Use `progress_namedOperator` to add/set operators for the specific namespace
-- Each Progress instance can have different operators for the same namespace
-- More flexible for dynamic team assignments
-
----
-
-## Function List
-
-| Function Name | Purpose | Usage Scenario | Significance |
-|---------------|---------|----------------|-------------|
-| **Create Progress** | Create new Progress from Machine | Start workflow execution from template | Entry point for all workflow executions |
-| **Object Reference** | Identify which Progress to operate on | Target specific workflow execution | Foundation for all Progress operations - defines which workflow instance to modify |
-| **Progress Operations (Accomplish)** | Execute forward and advance node | Complete workflow steps, move to next state | Core of workflow execution - processes transitions normally |
-| **Progress Operations (Hold)** | Lock operation at current node | Pause for review, prevent race conditions | Controls workflow execution flow and avoids conflicts |
-| **Progress Operations (Admin Unhold)** | Force unlock from hold state | Admin intervention, override holds | Provides emergency override capabilities |
-| **Named Operator Management** | Add/set/remove named operators | Dynamic permission assignment, team changes | Provides flexible access control for workflow stages |
-| **Set Task** | Associate Progress with a Task object | Link workflow to order, service request | Establishes relationship between workflow execution and business entities |
-| **Repository Management** | Attach/remove/clear Repository objects | Store execution data, state, deliverables | Enables data persistence during workflow execution |
-
----
-
-## Schema Tree
-
-> **Creating Progress**: Progress instances are created using `operation_type: "machine"` with the `progress_new` field. See [Machine Component](machine.md) for the `progress_new` schema definition.
-
-```
-progress (Operate Existing Progress)
-├── operation_type: "progress" (fixed value)
-├── data
-│   ├── object (string, required) - Progress name or ID to operate on
-│   ├── task (string, optional) - Task ID to bind (cannot be changed after setting)
-│   ├── repository (object, optional, ObjectsOp)
-│   │   ├── op: "add" | "set"
-│   │   │   └── objects (array of strings)
-│   │   ├── op: "remove"
-│   │   │   └── objects (array of strings)
-│   │   └── op: "clear"
-│   ├── progress_namedOperator (object, optional)
-│   │   ├── op: "add" | "set" | "remove"
-│   │   ├── name (string) - Non-empty namespace name (max 64 bcs characters)
-│   │   └── operators (object, ManyAccountOrMark_Address)
-│   │       ├── entities (array of AccountOrMark_Address)
-│   │       │   └── [{ name_or_address: "string", local_mark_first: boolean }]
-│   │       └── check_all_founded (boolean, optional)
-│   └── operate (object, optional)
-│       ├── operation (object, required)
-│   │   ├── next_node_name (string) - Target node name to advance to (max 64 bcs characters)
-│   │   └── forward (string) - Forward operation name defined in Machine (max 64 bcs characters)
-│       ├── hold (boolean, optional) - Lock operation permission
-│       ├── adminUnhold (boolean, optional) - Admin force unlock (only when hold=true)
-│       └── message (string, optional) - Operation result message
-├── env (optional)
-│   ├── account (string, optional) - Account name or address, empty string for default
-│   ├── network (string, optional) - "localnet" or "testnet"
-│   ├── permission_guard (array of strings, optional) - Permission guard IDs
-│   ├── no_cache (boolean, optional) - Disable cache
-│   └── referrer (string, optional) - Referrer ID
-└── submission (optional)
-    ├── type: "submission" (fixed value)
-    ├── guard (array) - Guards to verify
-    │   └── [{ object: string, impack: boolean }]
-    └── submission (array) - Submission data for guards
-        └── [{ guard: string, submission: [{ identifier, b_submission, value_type, value, name }] }]
-```
-
----
-
-### ⚠️ Important Note About Submission
-
-If the execution returns a `submission` field in the response, it indicates that additional Guard verification data is required. You must:
-
-1. Complete all required submission data within the `submission` structure
-2. Resubmit the operation with the completed submission data
-3. **Do not modify any other parts of the structure** - only fill in the required submission values
-
-The submission structure will specify which Guard objects need verification and what data needs to be provided for each Guard table item.
-
-**Query Value Types**: Use the `wowok_buildin_info` tool with `{ "info": "value types" }` to query all supported value types with their numeric and string representations.
-
----
-
-## Complete Tool Call Structure
-
-Progress operations use the following top-level structure:
-
-```json
-{
-  "operation_type": "progress",
-  "data": { ... },
-  "env": { ... },
-  "submission": { ... }
-}
-```
-
----
-
-## Creating Progress (via Machine)
-
-Progress instances are created from published Machine objects using `operation_type: "machine"` with the `progress_new` field. See [Machine Component](machine.md) for complete details.
-
-### Key Points
-
-- Use `operation_type: "machine"` with `data.progress_new`
-- The Machine must be published (only published Machines can create Progress)
-- When created, Progress's `current` field is set to `""` (empty string, the init node)
-- You need a forward with `prev_node: ""` in the Machine to advance from init to the first actual node
-
-### Quick Examples
-
-#### Create Simple Progress
-
-**Prompt**: Create a new Progress from "sdlc_workflow_v2" Machine.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "sdlc_workflow_v2",
-    "progress_new": {}
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Create Named Progress
-
-**Prompt**: Create a Progress named "project_gamma" from "sdlc_workflow_v2" Machine.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "sdlc_workflow_v2",
-    "progress_new": {
-      "namedNew": {
-        "name": "project_gamma",
-        "tags": ["mobile", "ecommerce"]
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Create Progress with Named Operators
-
-**Prompt**: Create a Progress and assign "dev_lead_carol" as operator for the "developer" namespace.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "sdlc_workflow_v2",
-    "progress_new": {
-      "namedNew": { "name": "project_delta" },
-      "progress_namedOperator": {
-        "op": "set",
-        "name": "developer",
-        "operators": {
-          "entities": [{ "name_or_address": "dev_lead_carol" }]
-        }
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Sub-feature 1: Operate Progress (operate)
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "object": "0x147f5f648a6e993bc5c29ae3a8143b8b5cb2b54a45cecb8ef1f81cf545292a5b",
-      "change": "created"
-    }
-  ]
-}
-```
-
-#### Example 1.2: Create Named Progress
-
-**Prompt**: Create a Progress named "project_gamma" with tags ["mobile", "ecommerce"].
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "sdlc_workflow_v2",
-    "progress_new": {
-      "namedNew": {
-        "name": "project_gamma",
-        "tags": ["mobile", "ecommerce"]
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 1.3: Create Progress with Named Operators
-
-**Prompt**: Create a Progress and assign "dev_lead_carol" as operator for the "developer" namespace.
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "sdlc_workflow_v2",
-    "progress_new": {
-      "namedNew": {
-        "name": "project_delta"
-      },
-      "progress_namedOperator": {
-        "op": "set",
-        "name": "developer",
-        "operators": {
-          "entities": [
-            {"name_or_address": "dev_lead_carol"}
-          ]
-        }
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Sub-feature 2: Operate Progress (operate)
-
-### Feature Description
-
-Advance Progress to the next node by executing node transition operations. There are two modes:
-- **Hold mode** (`hold: true`): Lock operation permission to avoid competition
-- **Accomplish mode** (`hold: false`): Submit operation result and advance
-
-### Parameter Description
-
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `operate.operation.next_node_name` | string | Yes | Target node name |
-| `operate.operation.forward` | string | Yes | Forward operation name |
-| `operate.hold` | boolean | No | Whether to hold at current node. When true, locks permission; when false or omitted, submits result directly |
-| `operate.adminUnhold` | boolean | No | Allow admin to force unlock (only when hold=true) |
-| `operate.message` | string | No | Operation message |
-
-### Important Notes
-
-⚠️ **Must have permission to execute the forward operation**.
-
-⚠️ **Must meet the threshold requirements of the forward operation**.
-
-⚠️ **Progress can only advance to the next node defined by the forward operation**.
-
-⚠️ **Task cannot be changed after setting**.
-
-### Examples
-
-#### Example 2.1: Advance from Init Node (First Step)
-
-**Prompt**: Advance "project_gamma" from init node (current: "") to "requirement" node using forward "start_project". This is the first step in the workflow.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_gamma",
-    "operate": {
-      "operation": {
-        "next_node_name": "requirement",
-        "forward": "start_project"
-      },
-      "message": "Starting new project from init node"
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet",
-    "no_cache": true
-  }
-}
-```
-
-> **💡 Tip**: The `hold` parameter is optional. When omitted or set to false, the operation submits the result directly and advances to the next node. Set `hold: true` only when you need to lock the operation permission.
-
-**Prerequisites**:
-1. Machine must have a node "requirement" with `prev_node: ""` and forward "start_project"
-2. Progress "project_gamma" was created from this Machine
-3. Progress's `current` field is `""` (init node)
-4. Operator has required permission for forward "start_project"
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "object": "0x147f5f648a6e993bc5c29ae3a8143b8b5cb2b54a45cecb8ef1f81cf545292a5b",
-      "change": "mutated"
-    }
-  ]
-}
-```
-
-> **Note**: After execution, the Progress's `current` field will change from `""` to `"requirement"`, and a history entry will be recorded.
-
----
-
-#### Example 2.2: Execute Accomplish Operation (No Hold)
-
-**Prompt**: Advance "project_alpha" from current node (requirement) to "design" using forward "submit_design", with message "Requirements approved, proceeding to design phase" and no hold.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "design",
-        "forward": "submit_design"
-      },
-      "message": "Requirements approved, proceeding to design phase"
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet",
-    "no_cache": true
-  }
-}
-```
-
-> **💡 Tip**: Set `env.no_cache: true` to ensure fresh data is fetched from the blockchain for each operation. This is especially important when executing multiple Progress operations in sequence.
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "type_raw": "0x2::progress::Progress",
-      "object": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f",
-      "version": "644547",
-      "owner": {
-        "Shared": {
-          "initial_shared_version": 639744
-        }
-      },
-      "change": "mutated"
-    },
-    {
-      "type": "TableItem_ProgressHistory",
-      "type_raw": "0x2::dynamic_field::Field<u64, 0x2::progress::History>",
-      "object": "0x20fe9fed2c2f7645dee9cf8b8c4148e13b399917ef1df7f12895fa32f838cb2a",
-      "version": "650074",
-      "owner": {
-        "ObjectOwner": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f"
-      },
-      "change": "created"
-    }
-  ]
-}
-```
-
-> **Important Note**: The forward name must exactly match the forward name defined in the Machine node. The system queries the Machine node by `next_node_name`, then looks for a pair where `prev_node` matches the current node, and finally finds the forward with matching name.
-
-**Prerequisites**: 
-1. The Machine must be published
-2. The Progress must be created from the Machine
-3. The operator must have the required permission (permissionIndex or namedOperator)
-4. The forward name must exactly match the name defined in the Machine node
-
-#### Example 2.3: Execute Hold Operation
-
-**Prompt**: Advance "project_alpha" from "design" to "development" using forward "start_development", hold at this node for architect review, with message "Design completed, awaiting architect approval".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "development",
-        "forward": "start_development"
-      },
-      "hold": true,
-      "message": "Design completed, awaiting architect approval"
-    }
-  },
-  "env": {
-    "account": "arch_bob",
-    "network": "testnet",
-    "no_cache": true
-  }
-}
-```
-
-> **💡 Tip**: When `hold: true`, the operation locks the permission at the current node, preventing other operators from executing competing operations. Use `adminUnhold: true` to allow admin override.
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "type_raw": "0x2::progress::Progress",
-      "object": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f",
-      "version": "644547",
-      "owner": {
-        "Shared": {
-          "initial_shared_version": 639744
-        }
-      },
-      "change": "mutated"
-    },
-    {
-      "type": "TableItem_ProgressHistory",
-      "type_raw": "0x2::dynamic_field::Field<u64, 0x2::progress::History>",
-      "object": "0x1099682492f682addbd65091eadee32c2dc7cdd4dc517672a72485aa517e0649",
-      "version": "648986",
-      "owner": {
-        "ObjectOwner": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f"
-      },
-      "change": "created"
-    }
-  ]
-}
-```
-
-#### Example 2.4: Admin Unhold Operation
-
-**Prompt**: Admin unlock "project_alpha" from hold state, allowing it to advance to "code_review" using forward "submit_code", with message "Design approved by admin, proceeding to development".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "code_review",
-        "forward": "submit_code"
-      },
-      "hold": true,
-      "adminUnhold": true,
-      "message": "Design approved by admin, proceeding to development"
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet",
-    "no_cache": true
-  }
-}
-```
-
-> **💡 Tip**: Use `adminUnhold: true` when you need to override a held operation. This requires admin privileges and should be used for emergency interventions or when the original operator is unavailable.
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "type_raw": "0x2::progress::Progress",
-      "object": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f",
-      "version": "644547",
-      "owner": {
-        "Shared": {
-          "initial_shared_version": 639744
-        }
-      },
-      "change": "mutated"
-    },
-    {
-      "type": "TableItem_ProgressHistory",
-      "type_raw": "0x2::dynamic_field::Field<u64, 0x2::progress::History>",
-      "object": "0xfe3a2f01d9f8d00f9755c783b2bbdb9e0a67eff31160bb079e18e38364c30369",
-      "version": "648986",
-      "owner": {
-        "ObjectOwner": "0x28d5f8d9cc3f4e2082827140739ee29b6e33125f7eeb586690a786cdb00bfe3f"
-      },
-      "change": "created"
-    }
-  ]
-}
-```
-
-#### Example 2.5: Using NamedOperator Forward
-
-**Prompt**: Developer "dev_lead_carol" advances "project_alpha" from "code_review" to "testing" using forward "submit_code" (which uses namedOperator "developer").
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "testing",
-        "forward": "submit_code"
-      },
-      "hold": false,
-      "message": "Code submitted for review"
-    }
-  },
-  "env": {
-    "account": "dev_lead_carol",
-    "network": "testnet"
-  }
-}
-```
-
-**Prerequisites**: The operator "dev_lead_carol" must be registered as a named operator for the "developer" namespace in this Progress instance.
-
----
-
-## Sub-feature 3: Manage Named Operators (progress_namedOperator)
-
-### Feature Description
-
-Manage named operators of Progress, used for dynamic permission assignment. Each Progress instance can have different operators for the same namespace, providing flexibility for dynamic team assignments.
-
-### Parameter Description
-
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `progress_namedOperator.op` | string | Yes | Operation type: add/set/remove |
-| `progress_namedOperator.name` | string | Yes | Namespace name |
-| `progress_namedOperator.operators` | object | Yes | Operator list configuration |
-| `progress_namedOperator.operators.entities` | array | Yes | Entity list with name_or_address |
-| `progress_namedOperator.operators.check_all_founded` | boolean | No | Check all entities are found |
-
-### Operation Type Description
-
-| Operation Type | Description |
-|----------|------|
-| `add` | Add new operators to the namespace |
-| `set` | Set (replace) operators in the namespace |
-| `remove` | Remove operators from the namespace |
-
-### Examples
-
-#### Example 3.1: Set Named Operators (Initial Assignment)
-
-**Prompt**: Set "developer" namespace to have "dev_lead_carol" as the operator for "project_alpha".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "progress_namedOperator": {
-      "op": "set",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "dev_lead_carol" }
-        ],
-        "check_all_founded": true
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523550",
-        "change": "mutated"
-      }
-    ]
-  }
-}
-```
-
-#### Example 3.2: Add Named Operators
-
-**Prompt**: Add "arch_bob" as an additional developer to "project_alpha" for collaborative development.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "progress_namedOperator": {
-      "op": "add",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "arch_bob" }
-        ],
-        "check_all_founded": true
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 3.3: Remove Named Operators
-
-**Prompt**: Remove "arch_bob" from "developer" namespace after their task is completed.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "progress_namedOperator": {
-      "op": "remove",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "arch_bob" }
-        ],
-        "check_all_founded": false
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 3.4: Multiple Named Operators
-
-**Prompt**: Set multiple developers for "project_beta" to enable team collaboration.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_beta",
-    "progress_namedOperator": {
-      "op": "set",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "arch_bob" },
-          { "name_or_address": "dev_lead_carol" },
-          { "name_or_address": "test_lead_dave" }
-        ],
-        "check_all_founded": true
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Sub-feature 4: Set Task (task)
-
-### Feature Description
-
-Set the task ID of Progress for associating with other objects. Task cannot be changed after setting. This is typically used to link a Progress to an Order, Service, or other business entities.
-
-### Parameter Description
-
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `task` | string | Yes | Task ID (name or address) |
-
-### Important Notes
-
-⚠️ **Task cannot be changed after setting**.
-
-### Examples
-
-#### Example 4.1: Set Task ID
-
-**Prompt**: Set task "mobile_app_order_001" for "project_alpha" to link it with the corresponding order.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "task": "mobile_app_order_001"
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-> **💡 Tip**: The `task` field can be set during Progress creation via `progress_new.task` or updated later using this operation. Once set, the task cannot be changed.
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523551",
-        "change": "mutated"
-      }
-    ]
-  }
-}
-```
-
-#### Example 4.2: Set Task with Service Reference
-
-**Prompt**: Link "project_beta" to service "web_development_service".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_beta",
-    "task": "web_development_service"
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Sub-feature 5: Manage Repository (repository)
-
-### Feature Description
-
-Manage repositories of Progress for storing workflow-related data. Repositories can store deliverables, documents, configuration, and other project artifacts.
-
-### Parameter Description
-
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `repository.op` | string | Yes | Operation type: add/set/remove/clear |
-| `repository.objects` | array | Required for add/set/remove | Repository list |
-
-### Operation Type Description
-
-| Operation Type | Description |
-|----------|------|
-| `add` | Add new repositories to the existing list |
-| `set` | Set (replace) the complete repository list |
-| `remove` | Remove specified repositories from the list |
-| `clear` | Clear all repositories |
-
-### Examples
-
-#### Example 5.1: Add Repositories
-
-**Prompt**: Add "project_alpha_specs" and "project_alpha_assets" repositories to "project_alpha" for storing specifications and design assets.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "add",
-      "objects": ["project_alpha_specs", "project_alpha_assets"]
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523552",
-        "change": "mutated"
-      }
-    ]
-  }
-}
-```
-
-#### Example 5.2: Set Repositories
-
-**Prompt**: Set "project_alpha" repositories to exactly ["project_alpha_code", "project_alpha_docs"], replacing any existing ones.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "set",
-      "objects": ["project_alpha_code", "project_alpha_docs"]
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 5.3: Remove Repositories
-
-> **⚠️ Note**: The `remove` operation may have limitations on the number of objects that can be removed at once. If you encounter errors, consider using `set` or `clear` operations instead.
-
-**Prompt**: Remove "project_alpha_specs" repository from "project_alpha".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "remove",
-      "objects": ["project_alpha_specs"]
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 5.4: Clear All Repositories
-
-**Prompt**: Clear all repositories from "project_alpha" after project completion.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "clear"
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Sub-feature 6: Combined Operations
-
-### Feature Description
-
-Execute multiple operations in one call to the Progress object. This is useful for complex workflow transitions that require updating multiple aspects simultaneously.
-
-### Examples
-
-#### Example 6.1: Complete Progress Workflow with All Features
-
-**Prompt**: For "project_alpha": 1) Set task "mobile_app_order_001", 2) Add "project_alpha_deliverables" repository, 3) Add "test_lead_dave" to "reviewers" namespace, 4) Advance to "testing" node with forward "approve_code", hold=false, message "Code review passed, moving to testing phase".
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "task": "mobile_app_order_001",
-    "repository": {
-      "op": "add",
-      "objects": ["project_alpha_deliverables"]
-    },
-    "progress_namedOperator": {
-      "op": "add",
-      "name": "reviewers",
-      "operators": {
-        "entities": [
-          { "name_or_address": "test_lead_dave" }
-        ],
-        "check_all_founded": true
-      }
-    },
-    "operate": {
-      "operation": {
-        "next_node_name": "testing",
-        "forward": "approve_code"
-      },
-      "hold": false,
-      "message": "Code review passed, moving to testing phase"
-    }
-  },
-  "env": {
-    "account": "dev_lead_carol",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "digest": "...",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523553",
-        "change": "mutated"
-      }
-    ]
-  }
-}
-```
-
-#### Example 6.2: Hold and Set Operators Together
-
-**Prompt**: For "project_alpha": 1) Hold at "uat" node with forward "pass_testing", 2) Add "customer_eve" to "approvers" namespace for UAT approval.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "progress_namedOperator": {
-      "op": "add",
-      "name": "approvers",
-      "operators": {
-        "entities": [
-          { "name_or_address": "customer_eve" }
-        ],
-        "check_all_founded": true
-      }
-    },
-    "operate": {
-      "operation": {
-        "next_node_name": "uat",
-        "forward": "pass_testing"
-      },
-      "hold": true,
-      "message": "Testing completed, awaiting UAT approval"
-    }
-  },
-  "env": {
-    "account": "test_lead_dave",
-    "network": "testnet"
-  }
-}
-```
-
-#### Example 6.3: Project Initialization with Multiple Setup Steps
-
-**Prompt**: Initialize "project_gamma" with task, repositories, and named operators in one operation.
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_gamma",
-    "task": "ecommerce_platform_order",
-    "repository": {
-      "op": "set",
-      "objects": ["project_gamma_specs", "project_gamma_designs", "project_gamma_code"]
-    },
-    "progress_namedOperator": {
-      "op": "set",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "dev_lead_carol" },
-          { "name_or_address": "arch_bob" }
-        ],
-        "check_all_founded": true
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
----
-
-## Real-World Example: Project Alpha - Complete SDLC Execution
-
-> **✅ All Features Operational**: This section demonstrates a complete, working workflow for Progress execution. All features including `operate` and `task` functions are fully functional as of SDK v2.1.29.
->
-> **Verified Working Features**:
-> - Progress creation from Machine
-> - Progress operate (forward execution with hold/accomplish modes)
-> - Named operator management (set/add/remove)
-> - Repository management (add/set/clear)
-> - Task setting and association
-
-This section demonstrates a complete, real-world implementation of executing a software development workflow using the Progress component. The examples are based on the Machine workflow created in the [Machine Component documentation](machine.md).
-
-### Project Overview
-
-**Project Name**: Project Alpha - Mobile App Development  
-**Machine**: software_dev_workflow (8-node SDLC workflow)  
-**Progress Address**: 0x5255...9cb4  
-**Team Structure**:
-- Product Manager (pm_alice) - Requirements approval
-- Architect (arch_bob) - Design approval  
-- Development Lead (dev_lead_carol) - Code review and deployment
-- Test Lead (test_lead_dave) - Testing approval
-- Customer (customer_eve) - UAT approval
-
-### Workflow Nodes
-
-```
-requirement → design → development → code_review → testing → uat → deployment → completed
-```
-
-### Prerequisites
-
-Before executing Progress operations, ensure you have:
-
-1. **Created and Published Machine**: `software_dev_workflow` (see [Machine Component](machine.md))
-2. **Created Progress Instance**: `project_alpha` with initial named operator
-3. **Granted Permissions**: Team members have appropriate permission indexes in the Permission object
-4. **Funded Accounts**: All team accounts have sufficient test coins
-
-### Step-by-Step Execution
-
-#### Step 1: Create Progress from Machine
-
-First, create a Progress instance from the published Machine:
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "software_dev_workflow",
-    "progress_new": {
-      "namedNew": {
-        "name": "project_alpha",
-        "tags": ["mobile", "ecommerce"]
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-      "change": "created"
-    }
-  ]
-}
-```
-
-#### Step 2: Initial Progress State
-
-After creation, `project_alpha` starts at the **init node** (`""`):
-
-```json
-{
-  "progress_name": "project_alpha",
-  "current_node": "",
-  "machine": "software_dev_workflow",
-  "named_operators": {},
-  "repositories": [],
-  "task": null
-}
-```
-
-> **Note**: The empty string `""` represents the init node. Progress always starts here when created.
-
-#### Step 3: Advance from Init Node to Requirement
-
-Execute the first forward to move from init node to "requirement" node:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "requirement",
-        "forward": "start_project"
-      },
-      "hold": false,
-      "message": "Starting Project Alpha - Mobile e-commerce app development"
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Prerequisites**:
-- Machine must have "requirement" node with `prev_node: ""` and forward "start_project"
-- Operator (pm_alice) must have permission for forward "start_project"
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": [
-    {
-      "type": "Progress",
-      "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-      "change": "mutated"
-    }
-  ]
-}
-```
-
-After execution, `current_node` changes from `""` to `"requirement"`.
-
-#### Step 4: Set Task and Repositories
-
-Link the Progress to the order and set up data repositories:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "task": "mobile_app_order_001",
-    "repository": {
-      "op": "set",
-      "objects": [
-        "alpha_requirements",
-        "alpha_designs", 
-        "alpha_code",
-        "alpha_test_reports"
-      ]
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523554",
-        "change": "mutated"
-      }
-    ]
-  }
-}
-```
-
-#### Step 5: Requirements to Design (PM Approval)
-
-Product Manager approves requirements and advances to design phase:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "design",
-        "forward": "submit_design"
-      },
-      "hold": false,
-      "message": "Requirements approved. Scope: Mobile e-commerce app with payment integration. Budget: $50,000. Timeline: 3 months."
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523555",
-        "change": "mutated",
-        "current_node": "design"
-      }
-    ]
-  }
-}
-```
-
-#### Step 6: Design to Development (Architect Approval)
-
-Architect reviews design and approves proceeding to development:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "development",
-        "forward": "start_development"
-      },
-      "hold": false,
-      "message": "Architecture design approved. Tech stack: React Native + Node.js + PostgreSQL. Microservices architecture with 3 services."
-    }
-  },
-  "env": {
-    "account": "arch_bob",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523556",
-        "change": "mutated",
-        "current_node": "development"
-      }
-    ]
-  }
-}
-```
-
-#### Step 7: Add Additional Developer
-
-Add another developer to the project for faster delivery:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "progress_namedOperator": {
-      "op": "add",
-      "name": "developer",
-      "operators": {
-        "entities": [
-          { "name_or_address": "arch_bob" }
-        ],
-        "check_all_founded": true
-      }
-    }
-  },
-  "env": {
-    "account": "pm_alice",
-    "network": "testnet"
-  }
-}
-```
-
-#### Step 8: Development to Code Review (Developer Submission)
-
-Developer submits code for review using namedOperator:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "code_review",
-        "forward": "submit_code"
-      },
-      "hold": true,
-      "message": "Initial implementation complete. Features: User auth, product catalog, shopping cart. 85% test coverage."
-    }
-  },
-  "env": {
-    "account": "dev_lead_carol",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523557",
-        "change": "mutated",
-        "current_node": "code_review",
-        "hold_status": "held"
-      }
-    ]
-  }
-}
-```
-
-#### Step 9: Code Review to Testing (Dev Lead Approval)
-
-Development lead reviews and approves code:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "testing",
-        "forward": "approve_code"
-      },
-      "hold": false,
-      "message": "Code review passed. All critical issues resolved. Ready for QA testing."
-    }
-  },
-  "env": {
-    "account": "dev_lead_carol",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523558",
-        "change": "mutated",
-        "current_node": "testing"
-      }
-    ]
-  }
-}
-```
-
-#### Step 10: Testing to UAT (Test Lead Approval)
-
-QA testing complete, move to User Acceptance Testing:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "add",
-      "objects": ["alpha_qa_report_v1"]
-    },
-    "operate": {
-      "operation": {
-        "next_node_name": "uat",
-        "forward": "pass_testing"
-      },
-      "hold": false,
-      "message": "QA testing complete. 47 test cases passed, 0 critical bugs, 2 minor UI issues documented."
-    }
-  },
-  "env": {
-    "account": "test_lead_dave",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523559",
-        "change": "mutated",
-        "current_node": "uat"
-      }
-    ]
-  }
-}
-```
-
-#### Step 11: UAT to Deployment (Customer Approval)
-
-Customer approves UAT and authorizes deployment:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "operate": {
-      "operation": {
-        "next_node_name": "deployment",
-        "forward": "approve_uat"
-      },
-      "hold": false,
-      "message": "UAT approved. All acceptance criteria met. Payment flow verified with test transactions. Ready for production."
-    }
-  },
-  "env": {
-    "account": "customer_eve",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523560",
-        "change": "mutated",
-        "current_node": "deployment"
-      }
-    ]
-  }
-}
-```
-
-#### Step 10: Deployment to Completed (Dev Lead)
-
-Final deployment to production:
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "project_alpha",
-    "repository": {
-      "op": "add",
-      "objects": ["alpha_deployment_logs", "alpha_production_config"]
-    },
-    "operate": {
-      "operation": {
-        "next_node_name": "completed",
-        "forward": "deploy_production"
-      },
-      "hold": false,
-      "message": "Successfully deployed to production. App Store: v1.0.0 live. Play Store: v1.0.0 live. Monitoring active."
-    }
-  },
-  "env": {
-    "account": "dev_lead_carol",
-    "network": "testnet"
-  }
-}
-```
-
-**Execution Result**:
-```json
-{
-  "message": "Transaction completed successfully",
-  "result": {
-    "type": "transaction",
-    "objectChanges": [
-      {
-        "type": "Progress",
-        "object": "0x5255787477424a2d17b8b9902957aaaf1f196d0c8a382ef52876153895dd9cb4",
-        "version": "523561",
-        "change": "mutated",
-        "current_node": "completed"
-      }
-    ]
-  }
-}
-```
-
-### Final Progress State
-
-```json
-{
-  "progress_name": "project_alpha",
-  "current_node": "completed",
-  "machine": "software_dev_workflow",
-  "named_operators": {
-    "developer": ["dev_lead_carol", "arch_bob"]
-  },
-  "repositories": [
-    "alpha_requirements",
-    "alpha_designs",
-    "alpha_code",
-    "alpha_test_reports",
-    "alpha_qa_report_v1",
-    "alpha_deployment_logs",
-    "alpha_production_config"
-  ],
-  "task": "mobile_app_order_001",
-  "execution_history": [
-    { "from": "", "to": "requirement", "by": "pm_alice", "forward": "start_project" },
-    { "from": "requirement", "to": "design", "by": "pm_alice", "forward": "submit_design" },
-    { "from": "design", "to": "development", "by": "arch_bob", "forward": "start_development" },
-    { "from": "development", "to": "code_review", "by": "dev_lead_carol", "forward": "submit_code" },
-    { "from": "code_review", "to": "testing", "by": "dev_lead_carol", "forward": "approve_code" },
-    { "from": "testing", "to": "uat", "by": "test_lead_dave", "forward": "pass_testing" },
-    { "from": "uat", "to": "deployment", "by": "customer_eve", "forward": "approve_uat" },
-    { "from": "deployment", "to": "completed", "by": "dev_lead_carol", "forward": "deploy_production" }
-  ]
-}
-```
-
-### Summary of Project Alpha Execution
-
-| Step | From Node | To Node | Operator | Forward | Duration |
-|------|-----------|---------|----------|---------|----------|
-| 0 | init ("") | requirement | pm_alice | start_project | Day 0 |
-| 1 | requirement | design | pm_alice | submit_design | Day 1 |
-| 2 | design | development | arch_bob | start_development | Day 5 |
-| 3 | development | code_review | dev_lead_carol | submit_code | Day 25 |
-| 4 | code_review | testing | dev_lead_carol | approve_code | Day 28 |
-| 5 | testing | uat | test_lead_dave | pass_testing | Day 35 |
-| 6 | uat | deployment | customer_eve | approve_uat | Day 40 |
-| 7 | deployment | completed | dev_lead_carol | deploy_production | Day 42 |
-
-**Total Project Duration**: 42 days  
-**Team Members Involved**: 5  
-**Workflow Transitions**: 8 (including init → requirement)  
-**Repositories Created**: 7  
-**Status**: ✅ Successfully Completed
-
----
-
-## Quick Start Guide
-
-### For New Users: Your First Progress Workflow
-
-Follow these steps to execute your first workflow:
-
-#### Step 1: Prerequisites Checklist
-
-Before starting, ensure you have:
-- ✅ A published Machine with properly configured nodes (including `prev_node: ""` for the first node)
-- ✅ Permission to create Progress from the Machine
-- ✅ Permission to execute forward operations
-- ✅ Sufficient test coins for transaction fees
-
-#### Step 2: Create Progress
-
-```json
-{
-  "operation_type": "machine",
-  "data": {
-    "object": "your_machine_name",
-    "progress_new": {
-      "namedNew": {
-        "name": "my_first_progress"
-      }
-    }
-  },
-  "env": {
-    "account": "your_account",
-    "network": "testnet"
-  }
-}
-```
-
-#### Step 3: Advance from Init Node
-
-```json
-{
-  "operation_type": "progress",
-  "data": {
-    "object": "my_first_progress",
-    "operate": {
-      "operation": {
-        "next_node_name": "first_node",
-        "forward": "start"
-      },
-      "hold": false,
-      "message": "Starting workflow"
-    }
-  },
-  "env": {
-    "account": "your_account",
-    "network": "testnet"
-  }
-}
-```
-
-> **Important**: The first forward must use `next_node_name` of the first node and `forward` name defined with `prev_node: ""` in the Machine.
-
-#### Step 4: Continue Workflow
-
-Repeat the operate operation for each subsequent node transition.
-
----
-
-## Important Notes
-
-⚠️ **Must have permission to execute forward operations**.
-
-⚠️ **Progress starts at init node ("") and needs `prev_node: ""` forward to reach first node**.
-
-⚠️ **Progress can only advance to nodes defined by forward operations**.
-
-⚠️ **Named operators are used for dynamic permission assignment**.
-
-⚠️ **Task is used for associating with other objects and cannot be changed after setting**.
-
-⚠️ **Repositories are used for storing workflow-related data**.
-
-⚠️ **Progress is created by Machine and cannot be created independently**.
-
-⚠️ **Hold mode locks operation permission to avoid competition**.
-
-⚠️ **AdminUnhold allows admin to force unlock (requires admin privileges)**.
-
----
-
-## Related Components
-
-| Component | Description |
-|-----------|-------------|
-| **[Machine](machine.md)** | Workflow template |
-| **[Service](service.md)** | WYSIWYG product trading |
-| **[Order](order.md)** | Order management |
-| **[Permission](permission.md)** | Permission management |
-| **[Repository](repository.md)** | Data ownership and usage rights |