ACTION_ID: output_shortcut
NAME: Output
CATEGORY: Floq Tools
CREDITS: 0

The fields a shortcut returns. Each mapped column becomes one entry in the
shortcut's output_schema, and a run's `output_data` carries one value per
column under that column's `name`.

⚠ You normally never add or configure this action yourself. Create
Shortcut and Update Shortcut take `outputs: [{name, value}]` and write this
node onto the workflow for you (appending it to the end of the chain when
there is none). A shortcut is frozen at publish, so configuring the node
directly changes NOTHING for the shortcut until Update Shortcut publishes a
new version — go through Update Shortcut instead.

1. INPUTS

column_names (jsonArray, required)
  The columns to return. Each item is `{name, value}`:
    name   The output field's public name — the key its value appears
           under in a run's `output_data` (e.g. "Company Website").
    value  What to return: a `{{ref}}` to an input (`{{input.<field>}}`)
           or an upstream action's output (`{{<action_instance_id>.<field>}}`),
           a literal, or a mix.
  Floqer keys each column internally from the item: the referenced field's
  id when `value` is exactly one reference token, otherwise the snake_cased
  `name`. Items with neither a `name` nor a usable `value` are dropped with
  an `unresolved_reference` warning on the 200.

2. OUTPUTS

One field per item in `column_names`, named by that item's `name`. They are
the shortcut's output_schema; they are not meant to be referenced by further
actions.

3. HOW TO CONFIGURE

The normal path — let Create Shortcut write the node:

POST /api/v1/shortcuts
{
  "workflow_id": "<workflow_id>",
  "name": "Company Enrichment",
  "outputs": [
    { "name": "Company Website", "value": "{{enrich_company_linkedin_profile_1.company_website}}" },
    { "name": "Employee Count",  "value": "{{enrich_company_linkedin_profile_1.employee_count}}" }
  ]
}

Changing the columns of an existing shortcut — Update Shortcut republishes:

PATCH /api/v1/shortcuts/{shortcut_id}
{
  "outputs": [
    { "name": "Company Website", "value": "{{enrich_company_linkedin_profile_1.company_website}}" }
  ]
}

4. KEY NOTES

- Create Shortcut reuses the workflow's existing `output_shortcut` action when there
  is one (it rewrites its columns) and appends one otherwise. Find its
  `action_instance_id` (`output_shortcut_<suffix>`) in Get Action Graph. A
  workflow with more than one (one per branch, built in the app) cannot be
  packaged or updated over the API — 400.
- A column whose `name` is unchanged keeps its internal key across Create and
  Update Shortcut, so renaming nothing is never a contract break.
- Column order in `column_names` is the order of output_schema.
- Configuring `column_names` directly (Configure Action) edits the workflow
  only. Runs execute the shortcut's frozen version and results are keyed by
  the shortcut's stored output_schema, so nothing changes until Update
  Shortcut publishes a new version.
- Get Action returns the items you configured, with the internal column key
  added; sending them back unchanged on a later PATCH keeps the same keys.

5. WHERE IT FITS IN A WORKFLOW

At the end of the chain. Upstream: whatever produced the values. Downstream:
nothing that needs its fields.

6. WHEN TO USE

- You want a run to return a fixed, named set of fields rather than every
  cell on the row — and you are reaching it through Create Shortcut or
  Update Shortcut.

7. WHEN NOT TO USE

- You are about to call Create Shortcut or Update Shortcut — pass `outputs`
  there instead.
- The shortcut already exists and you want different columns — Configure
  Action on this node will not change it; use Update Shortcut.
- The workflow is only ever run on sheets and read with List Rows — the
  action adds nothing there.
- You need to move rows somewhere: use push_data_to_sheet or
  push_data_to_another_floqer_workflow instead.