fix(flow): document --parent for nesting CLI-owned nodes in a loop (canonical)

[rockymadden]

What

Documents uip maestro flow node add --parent <containerId> — the supported way to nest a CLI-owned node (managed HTTP core.action.http.v2, connector activities/triggers) inside a core.logic.loop body — and states it once, in the canonical Node-ownership section, with the leaves reduced to pointers.

Why

Loop-body nodes require parentId. The skill only documented setting parentId directly in the JSON, which is valid for user-owned nodes (Script) but forbidden for CLI-owned nodes by the node-ownership rule (#9 — don't hand-edit connector/HTTP node JSON). That left no documented path to put a CLI-owned node in a loop.

The CLI already supports this via node add --parent, whose own help text reads:

"Id of the existing node that should contain this node. Set when authoring a loop body whose containment cannot be inferred from edges alone — typically the id of a core.logic.loop node."

…but no reference doc mentioned the flag.

Impact (root cause of a task failure)

In skill-flow-multi-city-weather, the agent correctly parented the in-loop Script node but added the HTTP node via node add (which lands it at top level, no parentId). The HTTP call therefore executed outside the loop, so $vars.fetchCurrentTemperature1.output was null on every iteration and the aggregated results contained no city data — failing the debug check. Critically, flow validate still passed (a missing parentId is structurally valid), so nothing surfaced the defect until runtime.

Approach — one canonical home, thin leaves

The --parent mechanism is a corollary of node ownership (a CLI-owned node can't be hand-edited, so its containment must also come from the CLI). So the principle lives once in the canonical section; everything else points to it.

Location	Role	Change
references/author/CAPABILITY.md § Node ownership	canonical statement	authoritative --parent bullet (covers all CLI-owned node types) + note that containment is the exception to "you may still Edit …"
SKILL.md rule #9	universal one-liner	terse --parent clause
references/author/references/editing-operations-cli.md	CLI reference	--parent row in the node add flags table; one-line pointer to the canon
plugins/loop/impl.md	loop-specific	short note + example + pointer; one debug-table row covering HTTP / connector ("output null every iteration")
plugins/loop/planning.md	loop-specific	one-line distinction (user-owned JSON vs CLI-owned --parent)

plugins/http/impl.md intentionally carries no --parent note: the rule is generic to every CLI-owned node, so special-casing HTTP would be arbitrary (connector activities/triggers have the identical concern). It's covered by rule #9, the canon, the CLI reference, and the loop debug row.

Docs only — no code or skill logic changed. Also fixes a wrong relative link depth (../../ → ../../../) to CAPABILITY.md.

Verification

• npm run skills:validate → OK (no new flavor replacements)
• scripts/check-cli-verbs.py on all edited files → 0 High / 0 Medium (node add --parent recognized against the uip 1.200.0-dev.8116 catalog)
• All introduced relative links + heading anchors verified to resolve

🤖 Generated with Claude Code

[github-actions]

Claude finished @rockymadden's task in 1m 45s —— View job

---

PR Review: fix(flow): document --parent for nesting CLI-owned nodes in a loop

• Read review criteria and project conventions
• Run diff and read changed files in full
• Check relative links resolve
• Check for cross-skill references, secrets, and conventions
• Post review findings

---

Summary

Documents --parent <loopId> on node add — the supported way to nest CLI-owned nodes (managed HTTP, connector activities/triggers) inside a core.logic.loop body. Four reference files updated with the flag, usage guidance, and debug-table rows. Docs-only change motivated by a real task failure where a missing parentId caused silent runtime misbehavior (output always null) that flow validate couldn't catch.

Change-by-Change Review

1. editing-operations-cli.md — --parent flag + nesting callout

OK

New --parent row in the flags table (line 34) and a blockquote callout (line 39) are well-placed — this is the canonical CLI flags reference, so any agent doing node add sees the flag immediately. The table description is clear and correctly notes the parent must already exist. The callout cross-references loop/impl.md#cli-owned-nodes-inside-a-loop, which resolves. Mentions "rule #9" for hand-editing prohibition — consistent with the existing node-ownership rule referenced elsewhere.

2. plugins/http/impl.md — loop callout + debug row

OK

Blockquote at line 49–56 placed directly after the "Add the node" code block is the right location — an agent following the HTTP walkthrough sees it in context. The code example correctly shows --parent <loopId> alongside the existing node add flags. Debug table row (line 202) describes the symptom precisely (output is null each iteration) and directs to the fix. Cross-reference link to ../loop/impl.md#cli-owned-nodes-inside-a-loop resolves correctly.

3. plugins/loop/impl.md — new ### CLI-owned nodes inside a loop section + debug row

OK

This is the authoritative section (line 53–62). Clean separation: user-owned → set parentId in JSON; CLI-owned → --parent on node add. The paragraph explains why (node-ownership rule), how (the flag), what happens if you don't (top-level placement, null output, validate still passes), and links back to CAPABILITY.md#node-ownership. Debug table row (line 251) matches the symptom/cause/fix pattern of the existing rows.

4. plugins/loop/planning.md — parentId bullet expanded

OK

Single-line expansion (line 52) of the existing parentId bullet to distinguish user-owned vs CLI-owned, with a cross-reference to impl.md#cli-owned-nodes-inside-a-loop. Compact and consistent with the planning file's role as a concise checklist.

What's Missing

Nothing identified. This is a focused docs-only patch that correctly places the new information in all four spots an agent would land when building a loop with CLI-owned nodes. No new CLI workflows were added, so no new test tasks are needed.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	Docs-only — no new workflows to test
Skill Body	OK	No SKILL.md changes
References & Assets	OK	All four reference changes are correct, well-placed, and internally consistent
Repo Hygiene	OK	No secrets, no cross-skill refs, no unrelated changes, all links resolve

Issues for Manual Review

• The PR states --parent is recognized against the uip 1.200.0-dev.8116 catalog. If this flag is only available in a dev/pre-release CLI version, confirm it will ship before agents encounter these docs in production. (Not verifiable from the repo alone.)

Conclusion

Clean, well-scoped documentation fix. All four placement points are correct — the information appears where an agent would naturally look when adding an HTTP or connector node to a loop body. Cross-references are consistent and all links resolve. No issues found; this looks good to merge.

---

[jiyangzh]

does the cli check if parent node is a loop?