# Update Stage

`Update_Stage` updates an existing GovTribe stage and returns the updated stage resource as JSON text.

## Input Contract

* `stage_id`: GovTribe ID of the stage to update.
  * `type`: `string`
  * `required`: `yes`
  * `default`: `n/a`
* `name`: Updated stage name.
  * `type`: `string`
  * `required`: `no`
  * `default`: `omit to keep current name`
  * `shape`: `min length 1, max length 50`
* `description`: Updated stage description text.
  * `type`: `string`
  * `required`: `no`
  * `default`: `omit to keep current description`
  * `shape`: `min length 1, max length 1000`
* `index`: Updated stage order value.
  * `type`: `integer`
  * `required`: `no`
  * `default`: `omit to keep current order`
  * `shape`: `min 0, max 996`
* `pursuit_index_map`: Optional pursuit-order payload for reordering pursuits within this stage.
  * `type`: `array<object>`
  * `required`: `no`
  * `default`: `omit to keep current pursuit order`
  * `shape`: `[{ "_id": "<PURSUIT_ID>", "index": <NON_NEGATIVE_INTEGER> }]`

## Output Contract

* Top-level keys:
  * `govtribe_id`
  * `govtribe_type`
  * `govtribe_url`
  * `name`
  * `description`
  * `type`
  * `created_at`
  * `updated_at`
  * `owner`
  * `creator`
  * `pipeline`
* Row keys:
  * `n/a`
* Relationship retrieval map:
  * `creator`
    * `resource_type`: `user`
    * `tool`: `Search_Users`
    * `filter`: `user_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `email`
  * `owner`
    * `resource_type`: `user`
    * `tool`: `Search_Users`
    * `filter`: `user_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `email`
  * `pipeline`
    * `resource_type`: `pipeline`
    * `tool`: `Search_Pipelines`
    * `filter`: `creator_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`

## Usage Patterns

Pattern A: Rename and reposition a stage in the pipeline sequence. Tool: `Update_Stage`

```json
{
  "stage_id": "<STAGE_ID>",
  "name": "Proposal Review",
  "index": 4
}
```

Pattern B: Update stage description while keeping current order. Tool: `Update_Stage`

```json
{
  "stage_id": "<STAGE_ID>",
  "description": "Gate for final compliance, pricing, and approval checks before submission."
}
```

Pattern C: Reorder pursuits inside a stage lane after pipeline review. Tool: `Update_Stage`

```json
{
  "stage_id": "<STAGE_ID>",
  "pursuit_index_map": [
    {
      "_id": "<PURSUIT_ID_1>",
      "index": 0
    },
    {
      "_id": "<PURSUIT_ID_2>",
      "index": 1
    }
  ]
}
```

Pattern D: Apply metadata updates and pursuit reordering in one idempotent request. Tool: `Update_Stage`

```json
{
  "stage_id": "<STAGE_ID>",
  "name": "Ready to Submit",
  "description": "Final stage before proposal handoff and release.",
  "index": 5,
  "pursuit_index_map": [
    {
      "_id": "<PURSUIT_ID_3>",
      "index": 0
    },
    {
      "_id": "<PURSUIT_ID_4>",
      "index": 1
    }
  ]
}
```