Address more review comments.

cylc/flow/cfgspec/workflow.py

@@ -1742,8 +1742,8 @@ def get_script_common_text(this: str, example: Optional[str] = None):
 
                 .. deprecated:: 8.3.0
 
-                Please use the workflow_state xtrigger instead:
-                :py:mod:`cylc.flow.xtriggers.workflow_state`.
+                Please use the :ref:`workflow_state xtrigger
+                <Built-in Workflow State Triggers>` instead.
             '''):
                 Conf('interval', VDR.V_INTERVAL, desc='''
                     Polling interval.

cylc/flow/config.py

@@ -1548,26 +1548,26 @@ def configure_workflow_state_polling_tasks(self):
                 "$CYLC_TASK_CYCLE_POINT/"
                 f"{tdef.workflow_polling_cfg['task']}"
             )
-            graph_trigger = tdef.workflow_polling_cfg['status']
-            config_trigger = rtc['workflow state polling']['message']
+            graph_selector = tdef.workflow_polling_cfg['status']
+            config_message = rtc['workflow state polling']['message']
             if (
-                graph_trigger is not None and
+                graph_selector is not None and
                 (
-                    config_trigger is not None
+                    config_message is not None
                 ) and (
-                    graph_trigger != config_trigger
+                    graph_selector != config_message
                 )
             ):
                 raise WorkflowConfigError(
                     f'Polling task "{name}" must configure a target status or'
-                    f' output message in the graph (:{graph_trigger}) or task'
-                    f' definition (message = "{config_trigger}") but not both.'
+                    f' output message in the graph (:{graph_selector}) or task'
+                    f' definition (message = "{config_message}") but not both.'
                 )
-            if graph_trigger is not None:
-                comstr += f":{graph_trigger}"
-            elif config_trigger is not None:
+            if graph_selector is not None:
+                comstr += f":{graph_selector}"
+            elif config_message is not None:
                 # quote: may contain spaces
-                comstr += f':"{config_trigger}" --messages'
+                comstr += f':"{config_message}" --messages'
             else:
                 # default to :succeeded
                 comstr += f":{TASK_OUTPUT_SUCCEEDED}"

cylc/flow/scripts/workflow_state.py

@@ -356,6 +356,13 @@ def get_option_parser() -> COP:
 @cli_function(get_option_parser, remove_opts=["--db"])
 def main(parser: COP, options: 'Values', *ids: str) -> None:
 
+    # Note it would be cleaner to use 'id_cli.parse_ids()' here to get the
+    # workflow ID and tokens, but that function infers run number and fails
+    # if the workflow is not installed yet. We want to be able to start polling
+    # before the workflow is installed, which makes it easier to get set of
+    # interdependent workflows up and running, so runN inference is done inside
+    # the poller. TODO: consider using id_cli.parse_ids inside the poller.
+
     if len(ids) != 1:
         raise InputError("Please give a single ID")
 

cylc/flow/xtriggers/workflow_state.py

@@ -27,7 +27,7 @@
 def workflow_state(
     workflow_task_id: str,
     offset: Optional[str] = None,
-    flow_num: Optional[int] = 1,
+    flow_num: Optional[int] = None,
     is_output: bool = False,
     is_message: bool = False,
     alt_cylc_run_dir: Optional[str] = None,
@@ -109,8 +109,11 @@ def validate(args: Dict[str, Any]):
         raise WorkflowConfigError(
             "Full ID needed: workflow//cycle/task[:selector].")
 
-    if not isinstance(args["flow_num"], int):
-        raise WorkflowConfigError("flow_num must be an integer.")
+    if (
+        args["flow_num"] is not None and
+        not isinstance(args["flow_num"], int)
+    ):
+        raise WorkflowConfigError("flow_num must be an integer if given.")
 
 
 # BACK COMPAT: workflow_state_backcompat