feat(commands): option groups, invocation scopes and the invocation record

extensions.md

@@ -178,7 +178,7 @@ const { defineCommand, inject } = require("nativescript/contracts");
 
 module.exports = defineCommand({
 	name: "hello|world",
-	arguments: "any",
+	params: "any",
 	async run(ctx) {
 		inject("logger").info(`Hello, ${ctx.args[0] || "world"}!`);
 	},
@@ -205,6 +205,23 @@ the command itself, executing that command fails with an error naming the
 extension, the command and the module — the entry points at the wrong file, or
 the file is not doing what the entry promises.
 
+Options and option groups
+-------------------------
+
+An extension's own commands declare options exactly as built-in commands do,
+option groups included. `defineOptions`, `CliOptions` and the option helpers
+are exported from `"nativescript/contracts"`, and a group a command lists under
+`options` is parsed with it and can be injected by services in its invocation
+(see [defining-commands.md](defining-commands.md#option-groups)).
+
+Adding options to a command the extension does not own, or to the
+process-level options, is not supported for a manifest-declared extension yet.
+The `OptionContributions` contract exists as a programmatic seam, and code
+whose module is loaded before the target parse can call it. A command module
+named in the manifest is loaded only when its own command is resolved, so it
+cannot add options to a built-in command the user invoked. A manifest-level
+way to declare a contribution does not exist yet.
+
 Command names
 -------------
 
@@ -218,7 +235,7 @@ rejected with a warning.
 **The manifest key decides how a command is invoked.** It has to: the CLI routes
 `ns hello world` to your module before that module has been loaded, so the key
 is the only name it can know. A `name` inside the definition is metadata — it is
-what `registerCommandDefinition` uses when a module registers itself, and it is
+what `registerCommand` uses when a module registers itself, and it is
 useful documentation, but a manifest entry overrides it. If the two disagree the
 CLI warns, naming both, and runs the command under the manifest key.