@uipath/maestro-builder-sdk 5.2.0

package/dist/generators/convert_library_to_md.py

@@ -0,0 +1,1441 @@
+#!/usr/bin/env python3
+"""Convert the canonical JSON connector library into a markdown library.
+
+Reads `<source>/index.json` and walks every entry — including the
+`generic/<object>/<op>@<ver>.json` entries the Generic CRUD expansion
+materializes — emitting a parallel tree of `.md` files plus a
+sibling `<output>/index.json` whose `path` fields point at the new
+`.md` files.
+
+The output tree is the shape coding agents read for connector
+discovery: header → connector / verb / object / HTTP → required
+inputs → optional inputs → outputs. The authoring agent's connector
+guidance (discovery pattern + Generic CRUD convention) lives in the main
+SKILL.md, not here — the per-op files stay focused on schema.
+
+Usage:
+    python3 convert_library_to_md.py --source <json-lib-dir> --output <md-lib-dir>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+
+# Symbol names cited below (`connector(SendMessageToUser, …)`, `.byEmail`) are
+# DERIVED, not stored — and derived by the descriptor generator. Both import the
+# same module so this page cannot cite a symbol that module did not emit.
+from _naming import by_aliases, symbol_index
+from _lookups import classify, load_invariant_collections, reference_of
+# The EXAMPLE is type-checked against the generated descriptor, so its required
+# set has to be the descriptor's, not this module's. The two vocabularies differ —
+# see example_lines.
+from generate_connectors_ts import (
+    input_fields as descriptor_input_fields,
+    is_container_part,
+    mark_lookup_fields as descriptor_mark_lookups,
+)
+
+
+
+
+def enum_value(v: object) -> str:
+    """One enum choice, as the literal an author would actually write.
+
+    The two schemas encode choices differently: ``inputSchema`` uses plain
+    strings (``"Prospect"``), while ``inputDefinition`` uses objects carrying a
+    display name alongside the wire value
+    (``{"name": "Abu Dhabi - Arabian Standard Time", "value": "Arabian Standard Time"}``).
+    Take ``value`` — that is what the flow has to send — so the rendering stays
+    identical across both shapes instead of leaking `{'value': …}` into the
+    catalog the agent reads.
+    """
+    if isinstance(v, dict):
+        return str(v.get("value", v.get("name", "")))
+    return str(v)
+
+
+def reference_collection(f: dict) -> str:
+    """The collection to call to resolve a field's value, or "".
+
+    Prefer `reference.path` over `reference.objectName`: the schema documents
+    `path` as the one "used for making the call to get the reference details",
+    and the two genuinely disagree. Data Service `entityName` declares
+    `objectName: "system"` but is served from `/standard-objects`, so building
+    the call from `objectName` sends an author to a collection that is not the
+    one holding the records.
+
+    Either side can carry a filter (`curated_channels?types=...`), and
+    `uip is resources run list` takes the collection positionally with the
+    filter as `--query`, so the two halves are split here rather than left for
+    a reader to guess.
+    """
+    reference = f.get("reference")
+    if not isinstance(reference, dict):
+        return ""
+    source = reference.get("path") or reference.get("objectName") or ""
+    if not isinstance(source, str) or not source:
+        return ""
+    return source.split("?", 1)[0].strip("/")
+
+
+def reference_query(f: dict) -> str:
+    """The filter half of whichever side `reference_collection` used, or ""."""
+    reference = f.get("reference")
+    if not isinstance(reference, dict):
+        return ""
+    source = reference.get("path") or reference.get("objectName") or ""
+    if not isinstance(source, str):
+        return ""
+    _, _, query = source.partition("?")
+    return query
+
+
+def authoring_field(f: dict) -> tuple[str, str, str]:
+    """Return the source-facing name/type and any distinct wire field name.
+
+    A top-level ``users[*]`` declaration is flattened wire notation. The
+    generated TypeScript descriptor exposes it as ``users: string[]``. Showing
+    the raw name as a scalar led authors to pass a comma-delimited
+    ``'users[*]'`` value that compiled but was not a valid multiselect.
+    """
+    wire_name = str(f.get("name", "?"))
+    type_ = str(f.get("type", "?"))
+    if wire_name.endswith("[*]") and "." not in wire_name:
+        return wire_name[:-3], f"{type_}[]", wire_name
+    return wire_name, type_, ""
+
+
+def enumeration_command(connector_key: str, f: dict) -> str:
+    """The `resources run list` call that shows what a field accepts.
+
+    Retained ONLY for identity lookups. For an ordinary lookup the helper
+    replaced this call, and leaving it on the page would offer two routes to the
+    same thing — the reader takes the one they already know, which is the manual
+    loop this whole surface exists to remove.
+
+    An identity lookup has no helper and no offline vocabulary (not one of them
+    carries an `enum`, measured across the shipped library), so removing the
+    command here would leave the field less documented than before. It is
+    reworded rather than deleted: not "how to resolve a name to an id" but "how
+    to see what this field accepts".
+    """
+    collection = reference_collection(f)
+    query = reference_query(f)
+    command = (
+        f"uip is resources run list {connector_key} {collection} "
+        f"--connection-id <id>"
+    )
+    if query:
+        command += f' --query "{query}"'
+    return command
+
+
+def lookup_lines(
+    connector_key: str, action: str, fields: list[dict], symbol: str | None,
+    invariant: set,
+) -> list[str]:
+    """The `## Resolving lookups` body: helpers first, commands only where owed.
+
+    An author reading this page has to turn something a human said ("send it to
+    Dustin") into the id the API wants. The old answer here was a `resources run
+    list` command and a manual paging loop. The answer now is a helper call and
+    one `prepare`, because the id is the wrong thing to write down: it is
+    meaningless in review and silently wrong after a move to another tenant.
+
+    `symbol` is the generated descriptor's exported name, or None when the
+    operation has no descriptor (a Generic CRUD expansion) — in which case the
+    string form of `lookup()` is what the example shows.
+    """
+    resolvable = [(f, reference_of(f)) for f in fields
+                  if classify(f, invariant) == "lookup"]
+    identity = [f for f in fields if classify(f, invariant) == "identity"]
+    if not resolvable and not identity:
+        return []
+
+    out: list[str] = []
+    if resolvable:
+        first_field, first_reference = resolvable[0]
+        # The lookup table is keyed by the WIRE name (`users[*]`), the same
+        # string `--resolve` and buildConnectorInputs match on. The table's
+        # `field` column keeps the authoring name, which is what the reader
+        # writes as an object key.
+        first_name = str(first_field.get("name") or authoring_field(first_field)[0])
+        first_names = [str(n) for n in (first_reference.get("lookupNames") or [])]
+        first_aliases = by_aliases(first_names)
+        # Without a descriptor the string form carries the real key AND action;
+        # a `<action>` placeholder here was a copy-paste trap, not a hint.
+        holder = symbol or f"'{connector_key}', '{action}'"
+        call = f"lookup({holder}, '{first_name}')"
+        sample = (f".{next(iter(first_aliases.values()))}('…')" if first_aliases
+                  else f".by('{first_names[0]}', '…')" if first_names else ".by('id', '…')")
+        # The MECHANISM — resolve, never hand-write the wire value — is true of
+        # every lookup. The old JUSTIFICATION was not: it asserted the value is
+        # an opaque, connection-specific id, which is false for 320 of the
+        # library's 2,563 rows and, on `uipath-salesforce-slack`
+        # `send-message-to-user`, for a row printed three lines below the claim
+        # (`send_as` sends the word `bot`) — #706.
+        #
+        # Nothing in the metadata says which case a field is in: a reference
+        # block carries only childPath, dependsOn, filterPattern, hydration,
+        # lookupNames, lookupValue, objectName and path. Classifying would mean
+        # guessing from the SPELLING of `lookupValue`, a list that goes stale
+        # the next time a connector ships a handle nobody thought of. So the id
+        # claim is stated as the CONDITION it always was, and the `sends` column
+        # — already printed below — answers which case this page is.
+        out.append(
+            "These fields send a value the connector defines, not the label you "
+            "know it by — the `sends` column says which. Do not write that value "
+            "by hand: where it is an opaque id it is also connection-specific, so "
+            "a pasted one resolves to nobody (or to somebody else) against a "
+            "different connection. Resolve it late:"
+        )
+        out.append("")
+        out.append("```ts")
+        # A dotted wire name is a legal object key only when quoted.
+        # `buildConnectorInputs` accepts the flat form as well as the nested
+        # one, so this stays a one-line illustration rather than growing into a
+        # second copy of the example below.
+        key = first_name if _IDENT.fullmatch(first_name) else json.dumps(first_name)
+        out.append(f"{key}: {call}{sample}")
+        out.append("```")
+        out.append("")
+        out.append("| field | helpers | matches on | sends |")
+        out.append("| --- | --- | --- | --- |")
+        for f, reference in resolvable:
+            name, _, _ = authoring_field(f)
+            names = [str(n) for n in (reference.get("lookupNames") or [])]
+            aliases = by_aliases(names)
+            helper_cell = (" ".join(f"`.{a}(v)`" for a in aliases.values())
+                           if aliases else "_(generic form only)_")
+            # `objectName` can carry a query string
+            # (`curated_channels?types=public_channel`). Show the collection.
+            target = (str(reference.get("objectName") or "").split("?", 1)[0]
+                      or reference_collection(f))
+            out.append(
+                f"| `{name}` | {helper_cell} | "
+                + " ".join(f"`{n}`" for n in names)
+                + f" | `{target}.{reference.get('lookupValue')}` |"
+            )
+        out.append("")
+        out.append("Any field also takes the generic form: `.by('<name>', value)`.")
+        out.append("")
+        # ORDERING, not just the command. "Resolve before compiling" read as
+        # "resolve now", and agents ran this prepare before a line of source
+        # existed (observed across four sessions). The page's job is the
+        # loop: author the token, let check name the command, run it once.
+        out.append(
+            "Author the `lookup()` call and finish the flow — `check` reports "
+            "each token still unresolved with exactly this command; run it "
+            "once before compiling (`compile` refuses an unresolved lookup):"
+        )
+        out.append("")
+        # ONE command carrying every --resolve. `prepare` calls accumulate into
+        # the same overlay, but a page printing one command per field reads as
+        # one round-trip per field, and the whole point is that it is one.
+        out.append("```bash")
+        # NO --connection-id. `prepare` discovers the connection itself and
+        # writes both keys into bindings.json. Showing the flag is what kept
+        # agents listing connections by hand first — measured 3/3 runs after the
+        # discovery landed, because every documented example still had it.
+        out.append(
+            f"npx flow-sdk registry prepare {connector_key} {action} \\"
+        )
+        resolves = []
+        for f, reference in resolvable:
+            name, _, _ = authoring_field(f)
+            names = [str(n) for n in (reference.get("lookupNames") or [])] or ["id"]
+            resolves.append(f"  --resolve {name}:{names[0]}=<value>")
+        out.extend(line + " \\" for line in resolves[:-1])
+        out.append(resolves[-1])
+        out.append("```")
+        out.append("")
+        strategies = {reference_strategy(r) for _, r in resolvable}
+        out.append(f"Strategy: {'; '.join(sorted(strategies))}.")
+        out.append("")
+
+    if identity:
+        out.append(
+            "**These fields take a plain string.** Their `reference` enumerates "
+            "the legal values rather than mapping a name to an id — what you "
+            "send back is what you searched for — so there is no helper and "
+            "nothing to resolve. The values exist only behind the connection, "
+            "so this is how to see what is accepted:"
+        )
+        out.append("")
+        out.append("```bash")
+        for f in identity:
+            name, _, _ = authoring_field(f)
+            out.append(f"# {name}")
+            out.append(enumeration_command(connector_key, f))
+        out.append("```")
+        out.append("")
+    return out
+
+
+def reference_strategy(reference: dict) -> str:
+    """Prose for how `prepare` will retrieve this collection."""
+    if reference.get("dependsOn"):
+        depends = ", ".join(f"`{d}`" for d in reference["dependsOn"])
+        return f"dependent — resolve {depends} first"
+    if reference.get("filterPattern"):
+        return "one request (server-side filter)"
+    if reference.get("childPath"):
+        return "hierarchical walk"
+    return "paged scan (no server-side filter declared)"
+
+
+def example_value(
+    f: dict, symbol: str | None, invariant: set,
+    connector_key: str = "", action: str = "",
+) -> str:
+    """The value to show for one required input.
+
+    Three rules, in order, and each is a decision rather than a detail:
+
+    * a resolvable lookup shows its helper — that is the whole point of the
+      helper existing, and an example that pasted an id would teach the opposite
+      of what `## Resolving lookups` says two sections above;
+    * an enum shows its FIRST DECLARED CHOICE, because that is a real legal
+      value and it shows the vocabulary at the same time;
+    * anything else shows `input('<name>')`, not a fake literal. A generated
+      `'<summary>'` compiles and is a lie; `input('summary')` compiles, is
+      idiomatic, and is honestly a placeholder. Copying it yields a flow that
+      declares the input rather than one carrying invented data.
+    """
+    name, _, _ = authoring_field(f)
+    # The lookup table is keyed by the WIRE name — `addLabelIds[*]`, not the
+    # authoring name `addLabelIds` — because that is what `--resolve` and
+    # `buildConnectorInputs` both match on. Passing the authoring name here is a
+    # type error at the `lookup(...)` call, which is how it was found.
+    wire = str(f.get("name") or name)
+    kind = classify(f, invariant)
+    if kind == "lookup":
+        reference = reference_of(f)
+        names = [str(n) for n in (reference.get("lookupNames") or [])]
+        aliases = by_aliases(names)
+        first = names[0] if names else "id"
+        if symbol:
+            if aliases:
+                return f"lookup({symbol}, '{wire}').{next(iter(aliases.values()))}('…')"
+            return f"lookup({symbol}, '{wire}').by('{first}', '…')"
+        # NO DESCRIPTOR — a Generic CRUD expansion. Its example is authored
+        # through the library by key/action/object, so the lookup has to be too,
+        # and the string form carries no typed aliases: only the generic `.by`.
+        # Emitting `lookup(<Descriptor>, …)` here was not a placeholder, it was
+        # a syntax error, on 614 pages.
+        return f"lookup('{connector_key}', '{action}', '{wire}').by('{first}', '…')"
+    type_ = str(f.get("type", "")).lower()
+    enum = f.get("enum")
+    if enum:
+        # The choice list is strings even when the field is not. Mailchimp's
+        # `email_type_option` declares `boolean` and offers "true"/"false", so
+        # emitting the choice verbatim produced `"true"` against a boolean.
+        # Where the choice cannot be typed to the declaration, fall back rather
+        # than emit something that does not compile.
+        choice = enum_value(enum[0])
+        if type_ in ("boolean", "bool"):
+            if choice.lower() in ("true", "false"):
+                return choice.lower()
+        elif type_ in ("number", "integer", "float", "double", "long"):
+            try:
+                float(choice)
+            except ValueError:
+                pass
+            else:
+                return choice
+        else:
+            return json.dumps(choice)
+    return f"input('{leaf_name(name)}')"
+
+
+def leaf_name(field_name: str) -> str:
+    """`fields.project.key` -> `projectKey`; a readable input name, not a path."""
+    parts = [p for p in field_name.replace("[*]", "").split(".") if p]
+    if not parts:
+        return "value"
+    if len(parts) == 1:
+        return parts[0]
+    tail = parts[-2:]
+    head, *rest = tail
+    return head + "".join(w[:1].upper() + w[1:] for w in rest)
+
+
+class _Node:
+    """One level of the example's input literal.
+
+    A segment can be BOTH an array and an object — `contacts[*].name` means a
+    list of objects — so array-ness is a flag on the node rather than a
+    different kind of node. Modelling it as "a list holding a value" is what an
+    earlier version did, and it crashed the moment a second field descended into
+    the same array.
+    """
+
+    __slots__ = ("children", "is_array", "leaf")
+
+    def __init__(self) -> None:
+        self.children: dict[str, _Node] = {}
+        self.is_array = False
+        self.leaf: str | None = None
+
+
+def nest_inputs(pairs: list[tuple[str, str]]) -> list[str]:
+    """Render `{name: value}` pairs as the nested object literal an author writes.
+
+    `buildConnectorInputs` accepts either the flat dotted key or the nested
+    object, but the descriptor's generated `Inputs` type is nested — so an
+    example using flat keys would not typecheck against the very descriptor it
+    imports. Wildcards (`users[*]`) become arrays for the same reason.
+    """
+    root = _Node()
+    for name, value in pairs:
+        node = root
+        for segment in [p for p in str(name).split(".") if p]:
+            is_array = segment.endswith("[*]")
+            key = segment[:-3] if is_array else segment
+            child = node.children.get(key)
+            if child is None:
+                child = node.children[key] = _Node()
+            child.is_array = child.is_array or is_array
+            node = child
+        node.leaf = value
+
+    def render(node: _Node, indent: int) -> list[str]:
+        pad = "  " * indent
+        lines: list[str] = []
+        for key, child in node.children.items():
+            safe = key if _IDENT.fullmatch(key) else json.dumps(key)
+            if child.children:
+                open_brace, close_brace = ("[{", "}],") if child.is_array else ("{", "},")
+                lines.append(f"{pad}{safe}: {open_brace}")
+                lines += render(child, indent + 1)
+                lines.append(f"{pad}{close_brace}")
+            else:
+                value = child.leaf if child.leaf is not None else "undefined"
+                lines.append(f"{pad}{safe}: [{value}]," if child.is_array
+                             else f"{pad}{safe}: {value},")
+        return lines
+
+    return render(root, 1)
+
+
+_IDENT = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+
+
+def example_lines(
+    j: dict, fields: list[dict], symbol: str | None, invariant: set,
+    v1def: dict | None = None,
+) -> list[str]:
+    """A compilable `connector(...)` call for this operation.
+
+    A page describes an operation's fields and never showed a call, so the agent
+    had to reconstitute the shape from a different document describing a general
+    form. The assembled answer is generatable from the same JSON, and the import
+    path is DERIVED rather than assumed: an operation whose schema arrives at
+    design time comes from `./connectors-local/` after a `prepare`, and saying
+    `./connectors/` for it would send the reader to a file that does not exist.
+
+    Required inputs only. The optional set runs to hundreds of fields on real
+    operations; an example showing them would not be an example.
+    """
+    connector_key = (j.get("connector") or {}).get("key") or "<connector>"
+    operation = j.get("operation") or {}
+    runtime = j.get("runtime") or {}
+    node_type = j.get("nodeType") or ""
+    action = node_type.rsplit(".", 1)[-1]
+    # WHICH REQUIRED SET. When a descriptor exists the example is type-checked
+    # against its `Inputs` interface, so the required set must be the one that
+    # interface declares — this module derives a different vocabulary, and the
+    # two disagree about required-ness on 4,529 of 7,036 operations (about the
+    # full field set on 6,164). Brevo `get-contact-by-email` is the shape of it:
+    # the page says "Required inputs: (none)" for an operation whose descriptor
+    # requires `email`, because the path parameter is picked up by one
+    # derivation and not the other.
+    #
+    # That disagreement is REAL and PRE-EXISTING, and reconciling it rewrites
+    # most of the markdown library — its own change, with its own review. Here
+    # the example simply follows the type it is checked against, so it compiles
+    # and is honest about what the descriptor wants.
+    #
+    # The string form takes `Record<string, unknown>`, so a generic example
+    # cannot fail on required-ness and keeps this module's vocabulary.
+    if symbol:
+        # v1def ships as either a dict or a one-element list; the descriptor
+        # generator normalises it the same way.
+        raw = v1def[0] if isinstance(v1def, list) and v1def else (v1def or {})
+        # Marked with the SAME call the descriptor generator uses, so the
+        # example puts a helper on exactly the fields that have one.
+        example_fields = descriptor_mark_lookups(
+            j, descriptor_input_fields(j, raw), invariant,
+        )
+    else:
+        example_fields = fields
+    required = [f for f in example_fields if f.get("required")]
+
+    schema_dynamic = bool(
+        operation.get("objectFromDiscovery")
+        or (operation.get("schemaAction") or {}).get("parents")
+        or runtime.get("requiresConnectionForSchema")
+    )
+    step = pascal_step(action)
+
+    if node_type.startswith(("uipath.connector.event.", "uipath.connector.trigger.")):
+        return event_example_lines(j, symbol, connector_key, action, step, v1def)
+
+    out = ["## Example", ""]
+    pairs = [(authoring_field(f)[0] if not authoring_field(f)[2] else f.get("name"),
+              example_value(f, symbol, invariant, connector_key, action))
+             for f in required]
+    # Import exactly what the rendered body uses. An example that references a
+    # helper it did not import does not compile, and a generated example that
+    # does not compile is worse than none: it is copied verbatim, and the reader
+    # spends turns working around a defect they did not author.
+    body_uses = {"connector"}
+    if any("lookup(" in v for _, v in pairs):
+        body_uses.add("lookup")
+    if any("input(" in v for _, v in pairs):
+        body_uses.add("input")
+    imported = ", ".join(sorted(body_uses))
+
+    out.append("```ts")
+    # THE PACKAGE, not a relative path. `@uipath/maestro-builder-sdk` is what an installed
+    # workspace resolves and what every shipped example uses; './sdk/flow-sdk.js'
+    # is a path that exists in no layout the docs describe, and an eval run
+    # caught an agent running `find / -iname flow-sdk.js` looking for it.
+    out.append(f"import {{ {imported} }} from '@uipath/maestro-builder-sdk';")
+    if symbol:
+        directory = "connectors-local" if schema_dynamic else "connectors"
+        out.append(f"import {{ {symbol} }} from './{directory}/{connector_key}.ts';")
+        out.append("")
+        head = f".step('{step}', connector({symbol}, {{"
+    else:
+        out.append("")
+        head = f".step('{step}', connector('{connector_key}', '{action}', {{"
+
+    out.append(head)
+    if pairs:
+        out += nest_inputs(pairs)
+    opts = []
+    if runtime.get("requiresConnection"):
+        opts.append(f"connection: '{connector_key.split('-')[-1]}'")
+    if runtime.get("requiresFolderKey"):
+        opts.append("folder: 'shared'")
+    if not symbol and operation.get("activityType") in ("Generic", "GenericExpanded"):
+        opts.append(f"object: '{operation.get('objectName') or '<object>'}'")
+    tail = "}" + (f", {{ {', '.join(opts)} }}" if opts else "") + "))"
+    out.append(tail)
+    out.append("```")
+    out.append("")
+    if schema_dynamic and symbol:
+        # ONE ordering per page. This trailer used to say "run prepare FIRST;
+        # the import does not resolve until you do" — which read as an
+        # instruction to prepare before authoring, on the same page whose
+        # header says author first. Two orderings on one page, and the agent
+        # takes the one it read last (observed: an agent front-loaded prepare
+        # for exactly this sentence). The import fact stays; the ordering
+        # instruction becomes the author-first contract.
+        if operation.get("objectFromDiscovery"):
+            out.append(
+                f"The descriptor comes from `./connectors-local/` and this "
+                f"import resolves only after "
+                f"`npx flow-sdk registry prepare {connector_key} {action} "
+                f"--object <name>` runs. That never blocks authoring: write "
+                f"the step first with the string form and "
+                f"`{{ object: '<name-as-the-task-said-it>' }}` — `check` "
+                f"names this exact prepare — then switch to this import."
+            )
+        else:
+            out.append(
+                f"The descriptor comes from `./connectors-local/` and this "
+                f"import resolves only after "
+                f"`npx flow-sdk registry prepare {connector_key} {action}` "
+                f"runs. That never blocks authoring: the fields in this "
+                f"catalog are authorable immediately, and `check` flags any "
+                f"input outside them with this same command."
+            )
+        out.append("")
+    return out
+
+
+def event_filter_lines(j: dict, v1def: dict | None) -> list[str]:
+    """The fields a subscription may filter on — and how complete that list is.
+
+    Without this the page named the event's PARAMETERS and stopped, so the one
+    thing an author needs in order to write `filters` was the one thing the
+    page did not say — while `check` refuses a leaf outside the vocabulary,
+    because the platform silently DROPS an unmatched one and the deployed
+    trigger then fires on everything.
+
+    The completeness caveat is the other half. Where a required query/path
+    parameter selects the schema (Jira's `project` / `issuetype`), the fields
+    below are what the connector reports with no values supplied, and no
+    discovery call accepts values — so that list is a baseline the real one
+    extends, `check` warns rather than refuses there, and the page has to say
+    so instead of implying the list is exhaustive.
+
+    TWO SOURCES, matching how the platform builds each kind of list — see
+    `Library.eventFilterFields`, which this page must agree with or `check`
+    refuses a leaf the page advertised. A CURATED event filters on the fields
+    its definition marks (`order: 1` / `isCuratedEventField`), which arrive as
+    `v1def.filterFields`; a GENERIC event filters on every field the object
+    supports GET on, which arrive as the entry's `outputSchema`. Reading the
+    marked list for both is what made Jira `record-created` advertise two
+    filterable fields where the designer offers 258.
+    """
+    node_type = j.get("nodeType", "")
+    if not node_type.startswith(("uipath.connector.event.", "uipath.connector.trigger.")):
+        return []
+    generic = (j.get("operation") or {}).get("activityType") == "GenericTrigger"
+    fields = list(((v1def or {}).get("filterFields") or {}).get("fields") or [])
+    if generic:
+        fields += (j.get("outputSchema") or {}).get("fields") or []
+    names: list[str] = []
+    for f in fields:
+        name = f.get("name")
+        if isinstance(name, str) and name and name not in names:
+            names.append(name)
+    if not names:
+        return []
+    selectors = [
+        f["name"] for f in ((v1def or {}).get("eventParameters") or {}).get("fields") or []
+        if f.get("required") and f.get("bucket") in ("query", "path")
+    ]
+    out = ["## Filtering", ""]
+    out.append(
+        "Narrow which records fire the subscription with `filters`. Each leaf is "
+        "`{ field, <operator>: value }` with exactly ONE operator "
+        "(`contains`, `startsWith`, `endsWith`, `equals`, `notEquals`, "
+        "`lessThan`, `lessThanOrEqual`, `greaterThan`, `greaterThanOrEqual`):"
+    )
+    out.append("")
+    out.append("```ts")
+    out.append(f"filters: [{{ field: '{names[0]}', contains: '<value>' }}]")
+    out.append("```")
+    out.append("")
+    out.append(
+        "Field names are CASE-SENSITIVE and only these are filterable — the "
+        "platform drops a leaf it does not recognise and the trigger then fires "
+        "on records the filter should have excluded, so `check` reports one that "
+        "is not here."
+    )
+    out.append("")
+    shown = ", ".join(f"`{n}`" for n in names[:40])
+    more = f" …and {len(names) - 40} more" if len(names) > 40 else ""
+    out.append(f"{shown}{more}")
+    out.append("")
+    if selectors:
+        listed = ", ".join(f"`{n}`" for n in selectors)
+        out.append(
+            f"> **This list is a baseline, not the whole vocabulary.** {listed} "
+            f"select this event's schema, and the connector derives its filter "
+            f"and output fields from their VALUES — which no discovery call "
+            f"accepts, so the fields above are the ones reported with none "
+            f"supplied. A name outside them may still be legal, which is why "
+            f"`check` warns rather than refuses here. Confirm it against the "
+            f"trigger in the designer before deploying."
+        )
+        out.append("")
+    elif any(
+        value for name, value in
+        (((j.get("connector") or {}).get("discovery") or {}).items()) if name != "type"
+    ):
+        # Distinct from the selector caveat above, and from the activity story:
+        # `resources describe` takes `-f`/`--action`, so preparing an ACTIVITY
+        # materializes its connection-scoped fields. `uip is triggers describe`
+        # takes neither, so for an event there is no call that reaches them and
+        # the list stays short however thorough the author is. Keyed on ANY
+        # discovery flag to match `Library.eventParameterFields.filtersPartial`
+        # — jira is classified `static` with `hasFieldDiscovery: true`, and it
+        # is the connector we have actually measured growing.
+        out.append(
+            "> **This list is a subset no `prepare` can complete.** This connector "
+            "reads its schema from the connection, and the trigger metadata call "
+            "takes no parent values — `uip is triggers describe` has no `-f`, the "
+            "flag that materializes an ACTIVITY's connection-scoped fields. So a "
+            "name outside the list above may be a real field of yours; `check` warns "
+            "rather than refuses, and the designer is where to confirm it."
+        )
+        out.append("")
+    return out
+
+
+def event_example_lines(
+    j: dict, symbol: str | None, connector_key: str, action: str, step: str,
+    v1def: dict | None = None,
+) -> list[str]:
+    """A compilable `onEvent(...)` / `waitForEvent(...)` call for a connector EVENT.
+
+    An event is not an action: its descriptor is a `triggerDescriptor()` that
+    `onEvent`/`waitForEvent` take, and `connector(...)` does not accept it. A
+    GENERIC event (`activityType: GenericTrigger`) watches ONE object of the
+    connection and its entry names none, so the example shows the `object`
+    option that names it; a curated event has its object built in, so the
+    example shows `where` with the event parameters the entry declares.
+    """
+    operation = j.get("operation") or {}
+    generic = operation.get("activityType") == "GenericTrigger"
+    start = node_type_is_start = j.get("nodeType", "").startswith("uipath.connector.trigger.")
+    # The SIDECAR's event parameters, for the same reason the typed `where`
+    # reads them: an entry nothing has described still carries the node's raw
+    # input definition, whose names (`filter.filters[*].id`) are not even legal
+    # object keys — the example stopped parsing when it was built from those.
+    # No parameters, no `where` in the example.
+    params = [
+        f["name"] for f in ((v1def or {}).get("eventParameters") or {}).get("fields") or []
+        if isinstance(f.get("name"), str) and not f.get("hidden")
+    ]
+    factory = "onEvent" if start else "waitForEvent"
+    out = ["## Example", "", "```ts"]
+    out.append(f"import {{ {factory} }} from '@uipath/maestro-builder-sdk';")
+    if symbol:
+        out.append(f"import {{ {symbol} }} from './connectors/{connector_key}.ts';")
+    out.append("")
+    opts = []
+    where_lines: list[str] = []
+    if generic:
+        opts.append("object: '<Object>'")
+    elif params:
+        # NESTED, exactly as inputs are: the generated `…Where` interface splits a
+        # dotted parameter into an object (`channelData.channel.id` becomes
+        # `channelData: ConnectorValue<ChannelDataInput>`), so a flat key — quoted
+        # or not — is not a member of the type. Unnested, Teams'
+        # `channelData.channel.id` made the only two event examples in the library
+        # the only `## Example` fences in ~8,000 that did not parse.
+        where_lines = ["  " + line for line in nest_inputs([(p, f"'<{p}>'") for p in params])]
+    opts.append(f"connection: '{connector_key.split('-')[-1]}'")
+    opts.append("folder: 'shared'")
+    lead = f"{factory}({symbol}, {{" if symbol else (
+        f"{factory}({{ connector: '{connector_key}', event: '{action}',"
+    )
+    if where_lines:
+        # Multi-line, like the action example, because the nested `where` is.
+        out.append(f".trigger({lead}" if start else f".step('{step}', {lead}")
+        out.append("  where: {")
+        out += where_lines
+        out.append("  },")
+        for option in opts:
+            out.append(f"  {option},")
+        out.append("}))")
+    else:
+        call = f"{factory}({symbol}, {{ {', '.join(opts)} }})" if symbol else (
+            f"{factory}({{ connector: '{connector_key}', event: '{action}', {', '.join(opts)} }})"
+        )
+        out.append(f".trigger({call})" if start else f".step('{step}', {call})")
+    out.append("```")
+    out.append("")
+    if generic:
+        out.append(
+            f"A GENERIC event: it fires for ONE object of the connection, so `object` "
+            f"names it. `uip is triggers objects {connector_key} "
+            f"{operation.get('eventOperation') or operation.get('name') or '<EVENT>'} "
+            f"--connection-id <id>` lists the objects the bound connection exposes."
+        )
+        out.append("")
+    del node_type_is_start
+    return out
+
+
+def pascal_step(action: str) -> str:
+    """`send-message-to-user` -> `sendMessageToUser`, a usable step name."""
+    words = [w for w in action.replace("_", "-").split("-") if w]
+    if not words:
+        return "step"
+    head, *rest = words
+    return head + "".join(w[:1].upper() + w[1:] for w in rest)
+
+
+def schema_action_lines(
+    connector_key: str, object_name: str, verb: str,
+    action: dict, fields: list[dict],
+) -> list[str]:
+    """How to get an operation's real field set when values select it.
+
+    Jira `create-issue` describes to 2 fields with nothing supplied and 32 once
+    a project and an issue type are given; a different issue type in the same
+    project gives a different set again. Salesforce SOQL is the same mechanism
+    driven by the query text. Without this section the page reads as an
+    operation that takes two inputs.
+    """
+    parents = action.get("parents") or []
+    if not parents:
+        return []
+    by_name = {f.get("name"): f for f in fields}
+    trigger = action.get("trigger")
+    replaces = action.get("replaces")
+    obj = object_name or "<object>"
+
+    out = ["## Resolving the field set", ""]
+    out.append(
+        "The inputs listed below are only the ones that SELECT the field set. "
+        "The real set depends on the values of "
+        + ", ".join(f"`{p}`" for p in parents)
+        + " — a different value gives a different set, so there is no single "
+        "field list for this operation."
+    )
+    out.append("")
+    if trigger:
+        out.append(
+            f"It is not automatic: `{trigger}` is a trigger rather than data, "
+            "so the schema has to be requested once the values are in place."
+        )
+        out.append("")
+    out.append("Resolve the parents in this order, then describe again:")
+    out.append("")
+
+    for position, parent in enumerate(parents, start=1):
+        reference = (by_name.get(parent) or {}).get("reference") or {}
+        collection = reference_collection(by_name.get(parent) or {})
+        if not collection:
+            out.append(
+                f"{position}. `{parent}` — supply the value; it is not chosen "
+                "from a list."
+            )
+            out.append("")
+            continue
+        query = reference_query(by_name.get(parent) or {})
+        pattern = reference.get("filterPattern") or ""
+        names = reference.get("lookupNames") or []
+        send = reference.get("lookupValue") or "id"
+        out.append(
+            f"{position}. `{parent}` — from `{collection}`"
+            + (f", match on {' or '.join(f'`{n}`' for n in names)}" if names
+               else "")
+            + f", send `{send}`."
+        )
+        # A placeholder means an earlier parent's value goes here.
+        if "{" in collection:
+            out.append(
+                "   Substitute the value resolved above for the "
+                "`{…}` part of the collection."
+            )
+        out.append("")
+        out.append("   ```bash")
+        command = (
+            f"   uip is resources run list {connector_key} {collection} "
+            f"--connection-id <id> \\"
+        )
+        out.append(command)
+        if pattern:
+            # The connector declares its own search. Substituting the
+            # wanted term narrows server-side and usually removes the
+            # paging: Jira project goes from 420+ rows across pages to 2
+            # in one call. It only works against the path the reference
+            # declares (`project/search`), not the plain object.
+            out.append(
+                '     --query "'
+                + pattern.replace("{filter}", "<search-term>")
+                + '" \\'
+            )
+        elif query:
+            out.append(f'     --query "{query}" \\')
+        projection = ",".join(
+            f"{n.split('[')[0]}:{n}" for n in (names[:2] or ["name"])
+        )
+        out.append(
+            f'     --output-filter "{{items: items[*].{{{projection},'
+            f"send:{send}}}, page: Pagination.{{h:HasMore,t:NextPageToken}}}}\" \\"
+        )
+        out.append("     --output json")
+        out.append("   ```")
+        out.append("")
+        if pattern:
+            out.append(
+                "   The connector declares its own search, so narrow with "
+                "the term the user gave rather than reading pages: one "
+                "call usually returns a handful, and `page` comes back "
+                "either absent or with `h` as `\"false\"`. Page only if "
+                "the term matches nothing."
+            )
+        else:
+            out.append(
+                "   Page it: `page.h` is the `elements-has-more` response "
+                "header verbatim, so it is the string `\"true\"` rather "
+                "than a boolean, and `page` is absent altogether when the "
+                "connector sends no pagination headers. While it reads "
+                "`\"true\"` and the value has not appeared, pass `page.t` "
+                "back as `--query \"nextPage=<token>\"` and read the next "
+                "page. Stop on the match. The projection keeps each page "
+                "small but does not reduce the call count."
+            )
+            out.append("")
+            out.append(
+                "   Before paging, check this field's `Reference` in the "
+                "`describe` output for a `FilterPattern`: it is "
+                "connection-scoped, so it is not in this catalog, but when "
+                "present it is the connector's own search and removes the "
+                "paging — Jira's project lookup declares `query={filter}`, "
+                "which turns 420-plus rows across pages into two in one call. "
+                "Substitute the wanted term into whatever pattern this field "
+                "declares; the shape is:"
+            )
+            out.append("")
+            out.append("   ```bash")
+            out.append(
+                f"   uip is resources run list {connector_key} {collection} "
+                f"--connection-id <id> \\"
+            )
+            out.append(
+                '     --query "<filter-pattern with the term substituted>" '
+                "--output json"
+            )
+            out.append("   ```")
+        out.append("")
+
+    supplied = " ".join(f"-f {p}=<value>" for p in parents)
+    out.append(f"{len(parents) + 1}. Describe again with the resolved values:")
+    out.append("")
+    out.append("   ```bash")
+    out.append(
+        f"   uip is resources describe {connector_key} {obj} "
+        f"--operation {verb} \\"
+    )
+    out.append(f"     --connection-id <id> {supplied} --output json")
+    out.append("   ```")
+    out.append("")
+    if replaces == "output":
+        out.append(
+            "   This replaces the **response** fields — it tells you the shape "
+            "of what comes back, not what to send."
+        )
+    elif replaces == "both":
+        out.append(
+            "   This replaces the **request** fields AND the **response** "
+            "fields — both halves of this operation change with the values "
+            "above, so read the response shape from the same call."
+        )
+    else:
+        out.append("   This replaces the **request** fields.")
+    out.append("")
+    # Only meaningful where the action rewrites the INPUT. Where it rewrites
+    # the output — a SOQL query, Jira `get-issue` — a resolved call leaves the
+    # request fields as exactly the parents, so telling a reader to treat that
+    # as failure makes every success look broken. Matches the gate in the CLI
+    # (`isParentOnlyResult`, UiPath/cli#3773).
+    if replaces in ("input", "both"):
+        out.append(
+            "If the result contains only the parents again, one of the values "
+            "does not exist on this connection. The call reports `Success` "
+            "either way, so the count alone cannot tell that apart from having "
+            "supplied nothing — check whether anything beyond the parents came "
+            "back. Too FEW parents fails loudly instead, with "
+            "`No api-type ObjectAction matched`."
+        )
+        out.append("")
+    return out
+
+
+def field_line(f: dict) -> str:
+    name, type_, wire_name = authoring_field(f)
+    desc = (f.get("description") or "").replace("\n", " ").strip()
+    enum = f.get("enum")
+    suffix = f", enum: {' | '.join(enum_value(e) for e in enum)}" if enum else ""
+    if wire_name:
+        suffix += f", wire field: `{wire_name}`"
+    # The wire slot, for a QUERY, PATH, or MULTIPART parameter. Body fields stay
+    # untagged so every existing line is byte-identical: `location` is the new
+    # information, and a field with none has always been a body field.
+    loc = f.get("location")
+    if loc in ("query", "path", "multipart"):
+        suffix += f", {loc}"
+    # Name the collection so the line itself says "this is a lookup, not free
+    # text". `Resolving lookups` below carries the call that resolves it.
+    collection = reference_collection(f)
+    if collection:
+        suffix += f", lookup: {collection}"
+    head = f"- `{name}` ({type_}{suffix})"
+    return f"{head} — {desc}" if desc else head
+
+
+# `operation.parameters[].type` → the wire slot, mirroring
+# `typescript/sdk/src/core/library.ts`'s PARAM_LOCATIONS.
+PARAM_LOCATIONS = {
+    "query": "query", "path": "path", "multipart": "multipart"
+}
+
+# A parameter's `dataType` → the scalar names `compile`'s literal type-check
+# understands (library.ts's `scalarType`).
+_SCALARS = {
+    "integer": "number", "number": "number", "double": "number",
+    "float": "number", "long": "number",
+    "boolean": "boolean", "string": "string",
+}
+
+
+def scalar_type(data_type: object) -> str:
+    return _SCALARS.get(data_type, data_type if isinstance(data_type, str) else "?")
+
+
+def param_fields(j: dict) -> list[dict]:
+    """The op's QUERY, PATH, and MULTIPART parameters as body-shaped fields.
+
+    These are inputs the COMPILER accepts — `core/library.ts`'s `readFields`
+    unions them with the v1def's body fields and tags each with its `location`,
+    which is what `serialize` routes on (flow-builder-sdk#132). The markdown was
+    written before that, so it documented the body half only.
+
+    That gap was large and, worse, silently wrong about REQUIREDNESS. Measured on
+    the shipped library (7,030 entries, 2026-07-31):
+
+    | | count |
+    |---|--:|
+    | entries carrying `operation.parameters` | **5,687** (81%) |
+    | parameters dropped | **14,872** (10,710 query · 4,162 path) |
+    | entries with a REQUIRED parameter | **4,413** (5,563 required params) |
+
+    Every one of those 4,413 rendered *"Required inputs: _(none)_"* — including
+    Jira `get-issue`, whose `{issueId}` path parameter the operation cannot run
+    without, and Data Service `query-entity-records`, whose required `entityName`
+    picks the entity. The tasks that used those ops named the parameters in their
+    own prompts, which is why nothing surfaced it.
+    """
+    out = []
+    for p in (j.get("operation") or {}).get("parameters") or []:
+        name = p.get("name")
+        loc = PARAM_LOCATIONS.get(p.get("type"))
+        if not isinstance(name, str) or not name or not loc:
+            continue
+        # A string-typed multipart part is the transport container the runtime
+        # composes from the body fields — documenting it as the REQUIRED input
+        # beside the real `body.content` is exactly what sent authors down
+        # `body: 'text'` (value ignored at dispatch) and `'body.content'`
+        # (refused by compile) on 2026-09-01. Only file parts are inputs.
+        if is_container_part(p):
+            continue
+        f = {"name": name, "type": scalar_type(p.get("dataType")),
+             "required": p.get("required") is True, "location": loc}
+        if p.get("description"):
+            f["description"] = p["description"]
+        if p.get("displayName"):
+            f["displayName"] = p["displayName"]
+        # `reference` says the value is an id resolved from a collection, not
+        # free text. Without it the page reads as "type anything here", which
+        # is how an author ends up sending a channel NAME where the API wants
+        # a channel id.
+        if p.get("reference"):
+            f["reference"] = p["reference"]
+        # A parameter's `enum` is deprecated in favour of `enhancedEnum`; the
+        # latter is what connectors actually populate.
+        if p.get("enum"):
+            f["enum"] = p["enum"]
+        elif p.get("enhancedEnum"):
+            f["enum"] = p["enhancedEnum"]
+        out.append(f)
+    return out
+
+
+def catalog_multipart_fields(j: dict) -> list[dict]:
+    """File fields whose older catalog entry omitted the multipart parameter."""
+    out = []
+    for field in (j.get("inputSchema") or {}).get("fields") or []:
+        if (
+            not field.get("name")
+            or str(field.get("type") or "").lower() != "file"
+        ):
+            continue
+        multipart = dict(field)
+        multipart["location"] = "multipart"
+        out.append(multipart)
+    return out
+
+
+def input_fields(j: dict, v1def: dict | None) -> list[dict]:
+    """The op's input fields, taken from the set the COMPILER validates against.
+
+    There are two candidate schemas per op and they disagree for 47% of curated
+    ops, so this choice is the whole point of the function:
+
+    * ``<op>.v1def.json`` → ``inputDefinition.fields`` — the Flow node's input
+      contract. ``core/library.ts:106`` loads exactly this into ``fields``, and
+      ``serialize.ts`` rejects anything outside it with `unknown input "…"`. The
+      generated typed descriptors use it too.
+    * ``<op>.json`` → ``inputSchema.fields`` — the connector's *API-level* schema
+      from the registry. Richer, and it includes parameters the Flow node does not
+      expose (pagination, ``where``/``orderBy``, upload ``file`` …).
+
+    File fields are the one exception: the Flow artifact has a multipart slot,
+    and older catalog snapshots can carry the file only in ``inputSchema``.
+    ``catalog_multipart_fields`` adds that transport field explicitly.
+
+    Documenting the second set makes the catalog advertise inputs the compiler
+    refuses. Measured over the shipped library: of 1,337 curated ops, **585**
+    listed at least one field that fails to compile, e.g. `pageSize` on
+    `uipath-act-act365.list-all-activities` →
+    `unknown input "pageSize"`. Another **49** hid a usable field the markdown
+    never mentioned. Where the name sets already agree (703 ops) the required
+    flags agree too, so those files are unchanged.
+
+    Falls back to ``inputSchema`` when an op ships no v1def, so nothing is lost
+    for entries the Flow layer does not model.
+    """
+    fields = ((v1def or {}).get("inputDefinition") or {}).get("fields")
+    if fields is None:
+        fields = (j.get("inputSchema") or {}).get("fields") or []
+    return fields
+
+
+def render_op(j: dict, v1def: dict | None = None, symbol: str | None = None,
+              invariant: set | None = None) -> str:
+    """Render one library entry to markdown.
+
+    Header layout (verb-first; both Curated and Generic share the same
+    shape — only the values differ):
+      # <nodeType>@<version>
+      **Connector:** <key> (<name>)
+      **Operation:** <verb>          ← `op.name`, e.g. Create / Delete / Retrieve
+      **Object:** <objectName>       ← when present
+      **Label:** <human-readable>    ← `display.label`, when distinct
+      **Description:** ...
+      **HTTP:** <method> <pathTemplate-or-path>
+    """
+    invariant = invariant or set()
+    node_type = j.get("nodeType", "?")
+    version = j.get("version", "?")
+    conn = j.get("connector", {}) or {}
+    op = j.get("operation", {}) or {}
+    display = j.get("display", {}) or {}
+
+    out: list[str] = []
+    out.append(f"# {node_type}@{version}")
+    out.append("")
+
+    conn_label = conn.get("key", "?")
+    if conn.get("name"):
+        conn_label += f" ({conn['name']})"
+    out.append(f"**Connector:** {conn_label}")
+
+    verb = op.get("name") or ""
+    if verb:
+        out.append(f"**Operation:** {verb}")
+
+    object_name = op.get("objectName") or ""
+    if object_name:
+        out.append(f"**Object:** `{object_name}`")
+
+    label = (display.get("label") or "").strip()
+    # Only show the human-readable label when it adds info beyond
+    # `<verb> <object>` (which an agent can reconstruct).
+    if label:
+        out.append(f"**Label:** {label}")
+
+    desc = (display.get("description") or "").strip()
+    if desc:
+        out.append(f"**Description:** {desc}")
+
+    http_method = op.get("httpMethod") or ""
+    http_path = op.get("pathTemplate") or op.get("path") or ""
+    if http_method and http_path:
+        out.append(f"**HTTP:** {http_method} {http_path}")
+
+    out.append("")
+
+    # Phase 1 marks every activity on a connector that advertises object/field
+    # discovery. Some activities are fully static, while others gain fields or
+    # objects from a live connection. Point the agent at `registry prepare`
+    # when the static library does not contain what it needs, without claiming
+    # every marked operation is necessarily incomplete.
+    if (j.get("runtime") or {}).get("requiresConnectionForSchema"):
+        key = conn.get("key") or "<key>"
+        prefix = f"uipath.connector.{key}."
+        action = node_type[len(prefix):] if node_type.startswith(prefix) else node_type.rsplit(".", 1)[-1]
+        # A discovery entry is missing something different from the rest, and
+        # `-f` cannot supply it. Of the 1,635 tier-1 pages carrying this block,
+        # 30 are discovery entries: they have no inputs, and what has to be
+        # resolved is the OBJECT. Pointing them at the parent-field loop and a
+        # `-f <parent-field>=<value>` command describes a job that does not
+        # apply, with a flag that cannot do it — `registry prepare` takes
+        # `--object` for this.
+        parents = ((j.get("operation") or {}).get("schemaAction") or {}).get(
+            "parents"
+        ) or []
+        discovery = bool((j.get("operation") or {}).get("objectFromDiscovery"))
+        if discovery:
+            out.append(
+                "> ⚠️ **The object is not in this catalog.** This node works on "
+                "any object in the connection, including custom ones, so it "
+                "carries no inputs here — what has to be resolved is the "
+                "OBJECT, not a field value. Author first, then one command "
+                "resolves it; **Choosing the object** below has the rules."
+            )
+            supply = "--object <name-as-the-task-said-it>"
+        else:
+            out.append(
+                "> ⚠️ **This operation resolves its real inputs from a live "
+                "connection.** The inputs listed below are only what the "
+                "tenant-agnostic snapshot carries. Do NOT hand-guess the "
+                "missing names."
+            )
+            out.append(">")
+            if parents:
+                # The section below names them, with the call that resolves
+                # each — repeating the generic advice here just lengthens it.
+                out.append(
+                    "> Its parents are named outright, with the call that "
+                    "resolves each one, under **Resolving the field set** "
+                    "below. Read that first."
+                )
+            else:
+                # Kept even when the entry declares no inputs: they arrive from
+                # the live describe, and the rule applies to them when they do.
+                # `test_dynamic_schema_markdown_teaches_the_parent_field_loop`
+                # holds this on every schema-dynamic op deliberately.
+                out.append(
+                    "> Any input whose reference path carries a `{placeholder}` "
+                    "is a parent: resolve a value for EVERY parent first, then "
+                    "prepare the operation with all of them. Too few parents is "
+                    "refused; a wrong VALUE is not — it resolves right back to "
+                    "the parent fields."
+                )
+            # A bare prepare must never read as sufficient here: an op with no
+            # declared inputs can still turn out to have parents once the live
+            # schema arrives, and "2 fields came back" looks identical to
+            # success. So the `-f` stays visible even when the catalog cannot
+            # name the parents — only the prose above adapts.
+            supply = (
+                " ".join(f"-f {name}=<value>" for name in parents)
+                if parents
+                else "-f <parent-field>=<value> ..."
+            )
+        out.append(">")
+        out.append("> ```bash")
+        # ONE spelling on every page, and it is the one `check` prints. #660
+        # measured the cost of the alternative: agents follow the documented
+        # form, so a legacy `prepare-connector --connection-id <id>` here while
+        # CUSTOM_FIELDS_UNPREPARED says `npx flow-sdk registry prepare` is two
+        # routes on one page — and the agent takes the one it already knows.
+        # No `--connection-id`: prepare discovers the connection itself and
+        # writes bindings.json (folder key included).
+        if discovery:
+            # The name is matched, not equality-tested, so the task's casing
+            # is fine as given.
+            out.append(
+                f"> npx flow-sdk registry prepare {key} {action} {supply}"
+            )
+        elif supply:
+            out.append(f"> npx flow-sdk registry prepare {key} {action} \\")
+            out.append(f">   {supply}")
+        else:
+            out.append(f"> npx flow-sdk registry prepare {key} {action}")
+        out.append("> ```")
+        out.append(">")
+        overlay = (
+            "> It writes a `./connectors-local/` overlay the compiler "
+            "auto-detects (its fields are unioned onto this entry)."
+        )
+        if not discovery:
+            # Pointing a discovery entry at the parent-field loop sends it to a
+            # section about resolving values for parents it does not have.
+            overlay += (
+                " The full loop — how to find the parents and resolve their "
+                "values — is in the connector guide "
+                "(`references/connector-params.md`) under \"Schema-dynamic "
+                "operations: the parent-field loop\"."
+            )
+        out.append(overlay)
+        out.append(
+            "> This requires a working live connection. For an explicitly "
+            "offline/validate-only flow that needs no connection-specific fields, "
+            "use the published static inputs below instead; a placeholder "
+            "connection cannot materialize a live schema. If that input list is "
+            "empty, pass `{}`: offline evidence proves operation identity and "
+            "control routing, not the provider payload or dispatch."
+        )
+        out.append("")
+
+    # Body fields, catalog-only files, then declared parameters. Older snapshots
+    # omitted a multipart parameter for some file uploads, while newer/live
+    # entries declare it directly. A parameter remains authoritative on location,
+    # so it REPLACES a same-named body or inferred multipart field.
+    fields = [dict(f) for f in input_fields(j, v1def)]
+    for p in [*catalog_multipart_fields(j), *param_fields(j)]:
+        at = next((i for i, f in enumerate(fields) if f.get("name") == p["name"]), -1)
+        if at >= 0:
+            # Fill gaps rather than replace: the entry's field may already
+            # carry a `reference` or `enum` this projection does not know
+            # about, and overwriting it loses the lookup.
+            merged = dict(fields[at])
+            merged.update({k: v for k, v in p.items() if v not in (None, "")})
+            for key in ("reference", "enum", "displayName"):
+                if key in fields[at] and key not in p:
+                    merged[key] = fields[at][key]
+            fields[at] = merged
+        else:
+            fields.append(p)
+    required = [f for f in fields if f.get("required")]
+    optional = [f for f in fields if not f.get("required")]
+
+    # Object selection comes before field selection, so it goes above the
+    # inputs. For these operations the inputs below are whatever holds for
+    # every object; the object's own fields arrive from step 2.
+    if op.get("objectFromDiscovery"):
+        connector_key = conn.get("key") or "<connector>"
+        verb = op.get("name") or "<operation>"
+        prefix = f"uipath.connector.{connector_key}."
+        md_action = (
+            node_type[len(prefix):] if node_type.startswith(prefix)
+            else node_type.rsplit(".", 1)[-1]
+        )
+        out.append("## Choosing the object")
+        out.append("")
+        out.append(
+            "This operation works on any object in the connection, including "
+            "custom ones, so the object list is not in this catalog. Do not "
+            "run discovery commands and do not hand-filter the catalog — "
+            "author the step with the object name as the task said it (any "
+            "casing), then one command matches it deterministically:"
+        )
+        out.append("")
+        out.append("```bash")
+        out.append(
+            f"npx flow-sdk registry prepare {connector_key} {md_action} "
+            "--object <name-as-the-task-said-it>"
+        )
+        out.append("```")
+        out.append("")
+        out.append(
+            "The name is matched, never equality-tested: exact, then "
+            "case-insensitive on API name and display name (`matched "
+            "\"Company__C\" -> Company__c` is printed), narrowed to objects "
+            f"that support {verb}. It then fetches the object's "
+            "connection-resolved fields, generates the typed descriptor, and "
+            "prints the import line to use."
+        )
+        out.append("")
+        out.append(
+            "**If the name matches several objects, the command refuses and "
+            "prints the candidates** (API name, display name, custom, "
+            "operations). `Custom: yes` marks an object that exists only on "
+            "this tenant, so it could never have been in this catalog — a "
+            "task that says \"custom\" means one of those rows. Pick by the "
+            "task's wording, or present the candidates and let the user "
+            "choose; never pick for them, and do not assume the user's "
+            "wording is the API name. Then re-run with the chosen name."
+        )
+        out.append("")
+        out.append(
+            "**If nothing matches**, the command has already retried against "
+            "a refreshed catalog before saying so — the object genuinely is "
+            "not on this connection. Check the value against the task's "
+            "words, or surface it to the user rather than inventing one."
+        )
+        out.append("")
+
+    action = op.get("schemaAction")
+    if action:
+        out.extend(schema_action_lines(
+            conn.get("key") or "<connector>",
+            op.get("objectName") or "",
+            op.get("name") or "<operation>",
+            action,
+            fields,
+        ))
+
+    out.append("## Required inputs")
+    out.append("")
+    if required:
+        out.extend(field_line(f) for f in required)
+    else:
+        out.append("_(none)_")
+    out.append("")
+
+    if optional:
+        out.append("## Optional inputs")
+        out.append("")
+        out.extend(field_line(f) for f in optional)
+        out.append("")
+
+    lookups = lookup_lines(
+        conn.get("key") or "<connector>",
+        node_type.rsplit(".", 1)[-1],
+        fields, symbol, invariant,
+    )
+    if lookups:
+        out.append("## Resolving lookups")
+        out.append("")
+        out.extend(lookups)
+        out.append("")
+
+    # The example goes AFTER the lookups section on purpose: it uses the helpers
+    # that section introduces, so a reader meets the rule before the usage.
+    out.extend(example_lines(j, fields, symbol, invariant, v1def))
+
+    out.extend(event_filter_lines(j, v1def))
+
+    out_fields = (j.get("outputSchema") or {}).get("fields") or []
+    if out_fields:
+        out.append("## Outputs")
+        out.append("")
+        out.extend(field_line(f) for f in out_fields)
+        out.append("")
+
+    return "\n".join(out)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--source", required=True,
+                   help="Source JSON library dir (must contain index.json)")
+    p.add_argument("--output", required=True,
+                   help="Destination dir for the markdown library")
+    return p.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    src = Path(args.source).resolve()
+    dst = Path(args.output).resolve()
+
+    index_path = src / "index.json"
+    if not index_path.is_file():
+        print(f"source library missing index.json: {index_path}", file=sys.stderr)
+        return 1
+
+    index = json.loads(index_path.read_text())
+    entries = index.get("entries", []) or []
+    # The SAME map the descriptor generator uses, so a symbol cited here is one
+    # it actually emitted. An entry absent from the map has no descriptor and
+    # its example is authored through the library instead (see symbol_index).
+    symbols = symbol_index(entries)
+    invariant = load_invariant_collections(src)
+
+    # Wipe and recreate destination so stale entries don't linger.
+    if dst.exists():
+        shutil.rmtree(dst)
+    dst.mkdir(parents=True, exist_ok=True)
+
+    converted = 0
+    for entry in entries:
+        rel_json = entry.get("path") or ""
+        if not rel_json or not rel_json.endswith(".json"):
+            continue
+        src_path = src / rel_json
+        if not src_path.is_file():
+            print(f"  WARN: missing source entry {src_path}", file=sys.stderr)
+            continue
+        j = json.loads(src_path.read_text())
+        # The Flow node shape lives beside the entry as `<op>.v1def.json`; its
+        # inputDefinition is what the compiler validates, so inputs are rendered
+        # from it (see input_fields). Outputs stay on the entry's outputSchema —
+        # v1def carries no output fields, and the descriptor generator agrees.
+        v1_path = src_path.with_name(src_path.name[:-5] + ".v1def.json")
+        v1def = json.loads(v1_path.read_text()) if v1_path.is_file() else None
+        md = render_op(j, v1def, symbols.get(entry.get("nodeType")), invariant)
+        rel_md = rel_json[:-5] + ".md"
+        out_path = dst / rel_md
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(md)
+        # Mutate the entry in place so the rewritten index points at .md.
+        entry["path"] = rel_md
+        converted += 1
+
+    (dst / "index.json").write_text(json.dumps(index, indent=2) + "\n")
+
+    print(f"wrote {converted} markdown ops to {dst}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())