docs(help): write the CLI help and command metadata in ASD-STE100

packages/command-registry/src/flag-definitions-connection.ts

@@ -12,7 +12,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--config <path>',
     usageDescription:
-      'Load CLI defaults from a specific config file (required for connection/provider defaults outside user config)',
+      'Load CLI defaults from a specific config file (required for connection or provider defaults outside the user config)',
     projectConfig: false,
     recorded: false,
   },
@@ -21,7 +21,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--remote-config'],
     type: 'string',
     usageLabel: '--remote-config <path>',
-    usageDescription: 'Load remote host + Metro workflow settings from a specific profile file',
+    usageDescription: 'Load remote host and Metro workflow settings from a specific profile file',
     projectConfig: false,
     recorded: false,
   },
@@ -31,7 +31,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--state-dir <path>',
     usageDescription:
-      'Daemon state directory (defaults to ~/.agent-device for packages, or a worktree-scoped dev dir from source)',
+      'Daemon state directory (default: ~/.agent-device for packages, or a worktree-scoped dev directory when run from source)',
     projectConfig: false,
     recorded: false,
   },
@@ -40,7 +40,8 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--daemon-base-url'],
     type: 'string',
     usageLabel: '--daemon-base-url <url>',
-    usageDescription: 'Explicit remote HTTP daemon base URL (skip local daemon discovery/startup)',
+    usageDescription:
+      'Explicit remote HTTP daemon base URL (skips local daemon discovery and startup)',
     projectConfig: false,
     recorded: false,
   },
@@ -50,7 +51,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--daemon-auth-token <token>',
     usageDescription:
-      'Remote HTTP daemon or proxy auth token (sent as request token and bearer header)',
+      'Remote HTTP daemon or proxy auth token (sent as the request token and the bearer header)',
     projectConfig: false,
     recorded: false,
   },
@@ -70,7 +71,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     enumValues: ['socket', 'http', 'dual'],
     usageLabel: '--daemon-server-mode socket|http|dual',
-    usageDescription: 'Daemon server mode used when spawning daemon',
+    usageDescription: 'Daemon server mode to use when the CLI spawns a daemon',
     projectConfig: false,
     recorded: false,
   },
@@ -79,7 +80,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--host'],
     type: 'string',
     usageLabel: '--host <host>',
-    usageDescription: 'Proxy: host interface to bind (default: 127.0.0.1)',
+    usageDescription: 'proxy: host interface to bind (default: 127.0.0.1)',
     projectConfig: false,
     recorded: false,
   },
@@ -90,7 +91,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     min: 1,
     max: 65535,
     usageLabel: '--port <port>',
-    usageDescription: 'Proxy: TCP port to bind (default: 0, choose a free port)',
+    usageDescription: 'proxy: TCP port to bind (default: 0, which selects a free port)',
     projectConfig: false,
     recorded: false,
   },
@@ -109,7 +110,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     enumValues: ['none', 'tenant'],
     usageLabel: '--session-isolation none|tenant',
-    usageDescription: 'Session isolation strategy (tenant prefixes session namespace)',
+    usageDescription: 'Session isolation strategy (tenant adds a prefix to the session namespace)',
     projectConfig: false,
     recorded: false,
   },
@@ -118,7 +119,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--run-id'],
     type: 'string',
     usageLabel: '--run-id <id>',
-    usageDescription: 'Run identifier used for tenant lease admission checks',
+    usageDescription: 'Run identifier for tenant lease admission checks',
     projectConfig: false,
     recorded: false,
   },
@@ -165,7 +166,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--provider-app <ref-or-path>',
     usageDescription:
-      'Cloud provider app reference or local app path used when creating hosted WebDriver sessions',
+      'Cloud provider app reference or local app path for the creation of hosted WebDriver sessions',
     projectConfig: false,
     recorded: false,
   },
@@ -185,7 +186,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     enumValues: PROVIDER_DEVICE_TYPES,
     usageLabel: '--provider-device-type real|virtual',
     usageDescription:
-      'TestMu AI device pool: real devices or virtual devices (emulators and simulators). Defaults to virtual',
+      'TestMu AI device pool: real devices, or virtual devices, which are emulators and simulators (default: virtual)',
     projectConfig: false,
     recorded: false,
   },
@@ -223,7 +224,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     enumValues: PROVIDER_DEVICE_ORIENTATIONS,
     usageLabel: '--provider-device-orientation portrait|landscape',
     usageDescription:
-      'Screen orientation a hosted cloud provider session starts in. Set this rather than rotating after launch: a session that boots landscape renders login webviews landscape',
+      'Screen orientation at the start of a hosted cloud provider session. Set this instead of a rotation after launch. A session that boots in landscape renders login webviews in landscape',
     projectConfig: false,
     recorded: false,
   },
@@ -251,7 +252,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--provider-appium-version <version>',
     usageDescription:
-      'Hosted cloud provider Appium server version, for example 3.2.0. Without it each provider starts its own default (Appium 1.x on BrowserStack)',
+      'Hosted cloud provider Appium server version, for example 3.2.0. Without it, each provider starts its own default version (Appium 1.x on BrowserStack)',
     projectConfig: false,
     recorded: false,
   },
@@ -299,7 +300,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'boolean',
     usageLabel: '--provider-no-resign-app',
     usageDescription:
-      'iOS only: keep an Enterprise-signed app as uploaded instead of letting the provider re-sign it, which strips entitlements such as push notifications',
+      'iOS only: keep an Enterprise-signed app as uploaded. Without it, the provider re-signs the app, which removes entitlements such as push notifications',
     projectConfig: false,
     recorded: false,
   },
@@ -355,7 +356,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'boolean',
     usageLabel: '--force, --overwrite',
     usageDescription:
-      'Force replacement of existing state (connect: replace an active connection; --save-script: overwrite an existing target instead of refusing)',
+      'Force the replacement of existing state (connect: replace an active connection; --save-script: overwrite an existing target instead of a refusal)',
     projectConfig: true,
     recorded: true,
   },
@@ -364,7 +365,8 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--clean'],
     type: 'boolean',
     usageLabel: '--clean',
-    usageDescription: 'Daemon stop: remove retained runner processes and leases after stopping',
+    usageDescription:
+      'daemon stop: remove retained runner processes and leases after the daemon stops',
     projectConfig: true,
     recorded: false,
   },
@@ -373,7 +375,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--no-login'],
     type: 'boolean',
     usageLabel: '--no-login',
-    usageDescription: 'Connect: fail instead of starting implicit cloud login',
+    usageDescription: 'connect: fail instead of starting an implicit cloud login',
     projectConfig: true,
     recorded: false,
   },
@@ -384,7 +386,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     enumValues: ['reject', 'strip'],
     usageLabel: '--session-lock reject|strip',
     usageDescription:
-      'Lock bound-session device routing for this CLI invocation and nested batch steps; strip drops conflicting platform/scope selectors only, and a selector naming a different device always fails',
+      'Lock bound-session device routing for this CLI invocation and its nested batch steps. strip removes only conflicting platform or scope selectors. A selector that names a different device always fails',
     projectConfig: true,
     recorded: false,
   },