Pipe build: create_phase index behavior is undocumented

[adriannoes]

Problem

create_phase accepts index, but it is unclear how index affects phase order and resulting connections/allowed moves. Agents set indexes and get surprising graph shapes.

Evidence

From live product testing against main:

• Passed index 1..8 when creating phases for a recruitment pipe.
• Resulting connections looked strange/incomplete (e.g. “Receber candidaturas” only connected back to “Anunciar”).
• Unclear how index influences order vs connections (connections themselves are not editable via API — see guidance issue).

Impact

Hard to build a predictable phase layout programmatically; trial-and-error and UI fixes.

Status on dev

MISSING (docs) — parameter exists (Optional position index within the pipe); SDK passes float when set. Docs/skill do not explain default, 0- vs 1-based, reorder, or relationship to connections.

Possible directions (non-binding)

• Document index semantics in tool docstring + pipes docs/skill
• Clarify interaction (or non-interaction) with phase connections / allowed_phases
• Examples for append vs insert-at-index
• Note API limits on editing connections so index is not mistaken for “wiring the flow”

Related: #392

Solution and acceptance criteria are decided when this issue is picked up.