Record ordinary Go numeric types for CLI JSON inputs

docs/roadmap/future.md

@@ -104,9 +104,11 @@ 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, integration
-installation collection, and selected text/file input forms; those flag and alias
+installation collection, selected text/file input forms, and CLI JSON number
-features need no core extension. Output-contract overrides and appended-message
+policy. Numeric conversion uses ordinary Go types and a small internal helper
-flags are deferred below. These are CLI features; general-purpose helpers for
+with policy comments. Those flag and alias features need no core extension.
+Output-contract overrides and appended-message flags are deferred below.
+These are CLI features; general-purpose helpers for
 application-internal PromptKit use are outside CommandKit's ownership boundary.
 
 - **Focused backend inspection.** Defer a standard backend detail command

docs/roadmap/promptkit-v0.19.0.md

@@ -570,8 +570,8 @@ selection, JSON conventions for core serialization, original Go values for text
 templates, no-template text rendering, universal formats, automatic selection,
 safe YAML input conversion, aggregate configuration presentation, or joint
 format delivery.
-Report serialization does not settle the separate JSON input-number conversion
+Report serialization is separate from the agreed CLI JSON number policy in OD-2
-choices in OD-2 and OD-11.
+and the remaining ConfigKit input-conversion decision in OD-11.
 
 ## Initial report implementation approach
 
@@ -749,6 +749,11 @@ Default tests remain offline and independent of real credentials.
 - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
   inputs through the existing usage path, and do not leak state between runs.
   Numeric decoding of provider JSON matches the selected strategy in OD-2.
+- [ ] The small, centralized internal CLI JSON conversion helper documents the
+  numeric policy and its rationale in code comments. Cover integer boundaries,
+  decimal/exponent forms, nested objects/arrays, and range errors. Accept ordinary
+  floating-point approximation; do not add arbitrary-precision fallbacks or a
+  public/general-purpose numeric conversion API.
 - [ ] The same public execution-flag collection works in a standard subcommand
   and an application-owned command with its own typed input. Parsing, presence,
   metadata, and selected subsets remain consistent; omitted retry values retain
@@ -888,10 +893,11 @@ The core ownership, JSON representation conventions, text printing/templates,
 universal-format, automatic-selection, and joint format-delivery decisions are
 now agreed above. Remaining details are listed under
 [remaining core reporting implementation details](#remaining-core-reporting-implementation-details).
-Outstanding integration choices are provider JSON decoding in OD-2, namespace
+Provider JSON number decoding is agreed in OD-2. Outstanding integration choices
-applicability in OD-3, empty comparison collections and binding design in OD-9,
+are namespace applicability in OD-3, empty comparison collections and binding
-and override grammar/acquisition details in OD-11. Exact helper names and report
+design in OD-9, and override grammar/acquisition details in OD-11. Exact helper
-layouts otherwise remain ordinary implementation choices, not unresolved scope.
+names and report layouts otherwise remain ordinary implementation choices, not
+unresolved scope.
 
 ### OD-1: Preview command and report presentation
 
@@ -921,9 +927,41 @@ dedicated preview template; a specialized template is not required for initial d
 core APIs. Give validation and preview the applicable execution controls already
 on smoke tests, and add a singleton `--llm-extra-params JSON` object option to
 all three. Use native whole-map replacement, including native behavior for
-empty maps. Specify JSON number decoding deliberately so supported values reach
+empty maps. The single-object form is selected over repeated key assignments.
-PromptKit without accidental precision loss or new numeric guarantees. The
+
-single-object form is selected over repeated key assignments.
+**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit.
+Classify numbers by their written JSON syntax, not by whether their mathematical
+value could be an integer:
+
+- Integer syntax (no decimal point or exponent) becomes `int64`. Nonnegative
+  values above its range become `uint64` when representable. Reject integers
+  outside those ranges with a clear input error; do not fall back to floating point.
+- Decimal or exponent syntax becomes `float64`: `42.0` and `1e3` remain floating
+  point even though their mathematical values are whole numbers. Accept ordinary
+  floating-point approximation; exact decimal representation is not required.
+  Report numeric range errors through the existing input-error path.
+- Apply the same rules recursively inside JSON objects and arrays, preserving
+  other JSON value types. Decode with the standard library's `UseNumber` to avoid
+  premature floating-point conversion, then convert the temporary `json.Number`
+  values before handing the object to PromptKit.
+
+Keep this in one small, centralized internal helper dedicated to CLI JSON input.
+Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose
+number conversion package, public conversion API, or extensible numeric framework
+is selected. CommandKit is a Go library for Go applications and deliberately
+accepts the precision and range of these Go types. It does not compensate for
+their limits with alternate numeric representations.
+
+**Required implementation comments:** document the syntax-based type selection,
+the `int64`/`uint64`/`float64` choices, accepted floating-point approximation,
+range-error behavior, and the rationale for this narrow boundary beside the
+helper. The comments must make clear that ordinary Go numeric limits are an
+intentional policy, not a missing feature to work around later.
+
+This policy governs parsed CLI provider parameters, not application-supplied
+runtime override values or core report serialization. ConfigKit input adaptation
+remains a separate decision under OD-11; do not broaden the helper into a generic
+conversion facility to anticipate that work.
 
 Retain the authoritative-builder rule: standard flags seed a request, and an
 application builder can return its complete replacement. Do not reapply CLI