Record explicit prompt input flags and text aliases

docs/roadmap/future.md

@@ -86,9 +86,10 @@ and the shared configuration inspection extensions. Its execution flags will be
 public reusable `ckprompt` collections for standard and application-owned CLI
 commands, composed through existing core bindings.
 [Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar)
-records the agreed canonical naming, scoped convenience aliases, and integration
+records the agreed canonical naming, scoped convenience aliases, integration
-installation collection; no core extension is required. Additional request-input
+installation collection, and selected text/file input forms; no core extension
-features remain open for individual review. These are CLI features;
+is required. Appended-message flags remain open for individual review. These
+are CLI features;
 general-purpose helpers for application-internal PromptKit use are outside
 CommandKit's ownership boundary.
 
@@ -103,11 +104,19 @@ CommandKit's ownership boundary.
   command syntax and report fields; this feature is outside the v0.19.0
   adoption scope.
 
-Additional request controls, including output-contract, inline-input, and
+- **Output-contract override flags.** Deferred from the current adoption. A
-appended-message flags, remain scope choices under
+  possible future operator task is validating or previewing one prompt with a
+  replacement output contract without editing its definition. PromptKit uses
+  whole-contract replacement; a complete-contract file option was discussed,
+  but no flag spelling or file format is selected. Existing configuration and
+  application builders remain available. Revisit when the standard `promptkit`
+  commands have a demonstrated need for this workflow.
+
+Appended-message flags remain a scope choice under
 [roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar).
-Their native API availability alone does not select CLI syntax or require a
+Inline text and explicit file input are now selected there for single-prompt
-convenience API for application execution.
+validation and preview. Native API availability alone does not select further
+CLI syntax or require a convenience API for application execution.
 
 ### Alias completion and discovery
 

docs/roadmap/promptkit-v0.19.0.md

@@ -94,7 +94,8 @@ in the decisions at the end of this document.
 
 | Operator task | Proposed CLI | Owning module and report |
 | --- | --- | --- |
-| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
+| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input-file … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
+| Supply a short sample to one prompt without creating a file | `promptkit show prepared PROMPT_ID --input NAME=TEXT`; also request validation | `ckprompt`: native inline input for single-prompt preparation; file input remains available through `--input-file NAME=PATH`. |
 | Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--llm-extra-params JSON` on these and smoke operations | `ckprompt`: native request forwarding; preview and smoke reports show returned effective settings. |
 | Resolve unqualified resource selections in chosen namespaces | Independent prompt/profile/backend namespace flags | `ckprompt`: delegate to native namespace views, retaining the distinction from catalog filters. |
 | Find configuration paths and inspect their explicitness | `config explain --list --scope promptkit`, with historical selection; metadata alongside path explanation | `ckconfig`, wired through `ckprompt.ConfigScope`: observed paths, effective presence, explicitness/null/origin evidence, and available history. |
@@ -186,7 +187,8 @@ values and whole-map replacement semantics. Support deliberate subsets for
 actual command needs while retaining common flag names and meanings, using a
 proportionate composition API. Keep parsing in CommandKit and domain validity
 in PromptKit. Existing application builders remain authoritative as agreed in
-OD-2; additional request-input controls remain open for individual review.
+OD-2. That decision also selects literal-text and file input bindings, defers
+output-contract overrides, and leaves appended-message controls open.
 
 ### Namespace selection
 
@@ -295,8 +297,9 @@ errors remain errors even if an override would replace the affected value.
    against the released notices and source commit. Update the unpublished
    candidate note and affected canonical dependency/compatibility guidance.
    No core Go-minimum increase follows from this adoption.
-3. **Implement request inspection and selection.** Add preview, applicable
+3. **Implement request inspection and selection.** Add preview, literal-text
-   override flags, provider-parameter input, and namespace selectors. Implement
+   input and renamed file-input flags, applicable override flags,
+   provider-parameter input, and namespace selectors. Implement
    public `ckprompt` execution-flag collections on existing core bindings and
    reuse them in the standard commands. Generate scoped convenience aliases and
    provide a collection for installing the commands and routing declarations.
@@ -357,8 +360,12 @@ Default tests remain offline and independent of real credentials.
 - [ ] The convenient installation collection includes commands and their scoped
   aliases; canonical-only installation remains available. Help and migration
   guidance explain both forms without requiring consumer-maintained alias lists.
-- [ ] Output-contract, inline-input, and appended-message options each receive
+- [ ] Text and file input names and aliases follow OD-2. Literal content,
-  an explicit scope decision before implementation.
+  including empty text, reaches native inline inputs; file bindings remain file
+  references. Examples, help, and documentation use the selected meanings.
+  Resolve and cover duplicate-name precedence across the two input forms.
+- [ ] Appended-message options receive an explicit scope decision before
+  implementation; output-contract override flags remain deferred.
 - [ ] Namespace defaults, explicit clearing, qualified selections, and catalog
   filters are forwarded according to the selected design.
 - [ ] The full configuration suite retains six subcommands. Explanation
@@ -427,6 +434,8 @@ handle lifecycle, sessions, and observer convenience APIs remain application
 responsibilities. Persistent configuration editing, new live probes, dynamic completion,
 JSON report formats, and unrelated deferred proposals are not added by this
 roadmap. Transient acquisition overrides remain an explicit choice in OD-11.
+Output-contract override flags are also deferred under OD-2 and retained in
+[future work](future.md#promptkit-inspection-and-selection-extensions).
 Discovery tracing and secrets-directory bootstrap commands remain deferred:
 the source inventory is not a trace of rejected search candidates, and bootstrap
 performs application startup effects.
@@ -493,11 +502,12 @@ applications may deliberately install convenience aliases on their own commands.
 | `--llm-prompt` | `--prompt` |
 | `--llm-session-id` | `--session-id` |
 | `--llm-var` | `--var` |
-| `--llm-input` | `--input` |
+| `--llm-input-text NAME=TEXT` | `--input-text`, `--llm-input`, `--input` |
+| `--llm-input-file NAME=PATH` | `--input-file` |
 
-Retain existing value syntax and units, including integer timeout seconds and
+Retain existing value syntax and units, including integer timeout seconds.
-file-backed input bindings. Commands taking a positional prompt ID retain that
+The input naming and content changes are specified below. Commands taking a
-argument; this naming decision does not add a redundant prompt flag. Execution,
+positional prompt ID retain that argument; this naming decision does not add a redundant prompt flag. Execution,
 resource-selection, and request-input collections may remain separately
 composable. Namespace controls remain subject to OD-3.
 
@@ -520,19 +530,47 @@ existing core API. Subtree alias scopes and a new core declaration-bundle type
 are not part of this adoption.
 
 Help should identify canonical names and their applicable aliases using current
-core presentation. Review published flag contracts during implementation and
+core presentation. CommandKit is alpha with no consumers; redesign without
-document migration, including retention of existing unprefixed spellings through
+compatibility constraints is explicitly accepted for these flags. Update implementation, examples, help, and documentation together; do not
-the convenience collection. Do not assume canonical-only installation preserves
+retain old meanings merely for compatibility. Canonical-only installation does
-those spellings.
+not supply convenience aliases.
 
-**Remaining request surface:** discuss output-contract overrides, inline-input
+**Agreed input forms:** include literal text alongside file input for
-flags, and appended-message flags individually before selecting scope and syntax.
+`promptkit requirements validate` and `promptkit show prepared`. The concrete
-Agreement to discuss these separately does not yet include or defer them.
+operator task is preparing one selected prompt with a short, disposable sample
-Existing file inputs and application builders continue to support preview. A
+without creating a fixture file. File inputs remain useful for substantial
-whole-output-contract file option and additional message/input options could
+content and repeatable artifacts. These operations make no model call and do
-support more reproduction workflows, with corresponding syntax, precedence,
+not establish model-output quality or application-workflow success. Assess
-and reporting decisions. No general-purpose request-building API follows from
+usefulness within these standard commands; speculative applicability to
-these CLI choices.
+multi-prompt application workflows is not a reason to add flags.
+
+Use the explicit canonical pair `--llm-input-text NAME=TEXT` and
+`--llm-input-file NAME=PATH`. The scoped aliases in the table include both
+`--input` and `--llm-input` for literal text. They route to the original text
+binding with the same parsing, presence, and occurrence-order behavior.
+`--input` no longer means a file path; file bindings use the explicit file form.
+Do not infer file access from literal content that resembles a path.
+
+Provide repeatable named bindings, splitting at the first `=` and preserving
+literal content, including explicit empty text, through native `Inline` inputs.
+File bindings continue to use native `File` references. Keep the canonical
+forms available through reusable request-input collections; application commands
+choose whether these bindings fit their workflow and may opt into aliases.
+None of these aliases is application-wide by default. Do not add prompt-input
+flags to smoke tests, which use their own diagnostic content.
+
+Duplicate-name precedence across text and file bindings remains a design point
+for review. The current recommendation is last command-line occurrence wins
+across both forms; this is not yet an agreed cross-binding ordering contract.
+
+**Deferred output-contract overrides:** no CLI override is included in this
+adoption. Retain the candidate in
+[future work](future.md#promptkit-inspection-and-selection-extensions);
+existing configuration and application builders remain available.
+
+**Remaining request surface:** discuss appended-message flags individually
+before selecting scope and syntax. No general-purpose request-building API
+follows from these CLI choices.
 
 ### OD-3: Namespace flags and loader defaults