Document PromptKit requirements discovery

docs/cli.md

@@ -382,6 +382,85 @@ error identity. Cancellation is also operational: standard handlers check the
 caller's context at inspection boundaries, and PromptKit can return cancellation
 from its own inspection methods. Supported cancellation identity is preserved.
 
+## PromptKit requirements
+
+When `Suite.InspectRequirements` is present,
+`ckprompt.Command(suite)` installs the following optional operation. It accepts
+one required prompt ID and uses PromptKit's native selection and discovery
+rules:
+
+```text
+example promptkit requirements show briefing --campaign spring
+example promptkit requirements show briefing --version 2 --profile editorial --var mode=full
+example promptkit requirements show briefing --session-id session-42 --var note= --format yaml
+```
+
+The command accepts these flags:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
+| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
+| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
+| `--version` | string | empty | Pass the prompt version to PromptKit; empty uses its native version-selection rule. |
+| `--profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native profile-selection rule. |
+| `--session-id` | string | empty | Pass session context to PromptKit. |
+| `--var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. |
+| `--format` | `yaml` | `yaml` | Select the requirements report format. Other formats are usage errors for this operation. |
+
+The `promptkit` namespace identifies the PromptKit operation, so there is no
+built-in `--scope` flag. The version, profile, and session fields use native
+empty-string semantics: an explicit empty string has the same meaning as
+omission. PromptKit owns their interpretation, including default version and
+profile selection, session context, and selection errors. Requirements
+inspection does not require a profile to be execution-ready. See the pinned
+[PromptKit requirements API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/requirements.go)
+for the owning discovery contract. The built-in flags are singleton bindings;
+when repeated, the last value is used. Suite selectors retain their declared
+binding behavior.
+
+Each `--var` occurrence must contain `=`. CommandKit splits at the first
+separator and preserves the exact key and remaining value. Empty keys and
+values, whitespace, commas, and additional `=` characters are retained. All
+occurrences are parsed; duplicate keys use the last value, while any malformed
+occurrence is a usage error even if a later assignment is valid.
+
+The successful report is YAML with selected identities, native completeness,
+and the input, variable, and issue inventories. False values and empty
+inventories are retained. Input metadata preserves null versus an empty string.
+The shape is:
+
+```yaml
+prompt_id: briefing
+prompt_version: "2"
+profile_id: editorial
+complete: false
+inputs:
+  - name: notes
+    kind: conditional
+    declared: false
+    content_type: null
+    description: null
+    explanation: ""
+variables: []
+issues:
+  - code: missing_variable
+    input_name: ""
+    variable_name: mode
+    description: ""
+```
+
+PromptKit owns the inventory, classifications, explanations, completeness,
+and structured issues. Completeness means discovery covered the relevant
+dependencies; it does not mean inputs or variables are supplied, artifacts are
+valid, credentials are available, or execution is ready. A complete report can
+contain unsupplied required variables, and an incomplete report can still be
+useful. Successfully acquired and delivered partial reports return status `0`;
+structured issues remain in YAML and do not independently fail the command.
+Provider errors, native selection errors, cancellation, and report delivery
+failures use the operational path (status `1`) with supported cause identity.
+Syntax, operand, variable-assignment, and format errors use usage status `2`.
+
 ### PromptKit catalogs
 
 An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by