Add session and reasoning controls

docs/api.md

@@ -45,6 +45,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
 | `prompt_id` | yes | Non-blank prompt ID. |
 | `prompt_version` | no | Prompt version filter. |
 | `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
+| `session_id` | no | Optional direct, non-secret session identifier. |
 | `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
 | `vars` | no | Object mapping template-variable names to strings. |
 | `model` | no | Runtime model-override object. |
@@ -77,6 +78,12 @@ field cause `400 invalid_json`.
 inherits the selected profile, a non-empty string replaces its value, and an
 empty string explicitly clears it. JSON `null` is treated as omission.
 
+`session_id` is passed directly to Promptkit. A nonblank value replaces a
+definition-rendered session ID; omission or a blank value lets the definition
+provide one. Promptkit trims direct values and limits them to 256 Unicode code
+points. Session IDs are not credentials and may be included in prepared data,
+results, and provider-facing requests, so use stable non-sensitive identifiers.
+
 ### Strict JSON
 
 Request decoding rejects malformed JSON, unknown fields at every request level,
@@ -104,6 +111,10 @@ validation contract. The response contains:
 `total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
 cache usage is reported as zero.
 
+When Promptkit resolves a direct or definition-rendered session ID,
+`metadata.session_id` contains that effective result value. It is omitted when
+no effective session ID exists.
+
 A validation failure has `validation.status: "failed"`, `is_valid: false`,
 and any available diagnostic errors, while still returning the artifact and
 metadata.

docs/cli.md

@@ -50,6 +50,7 @@ Optional flags:
 | `--schema-dir <dir>` | Schema base-directory override. |
 | `--prompt-version <version>` | Optional prompt-definition version selector. |
 | `--profile <id>` | Execution-profile override. |
+| `--session-id <id>` | Optional direct session identifier. |
 | `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
 | `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
 | `--out <path>` | Write generated content to this file instead of stdout. |
@@ -59,6 +60,7 @@ Optional flags:
 | `--temperature <float>` | Runtime temperature override. |
 | `--max-tokens <int>` | Runtime maximum-token override. |
 | `--top-p <float>` | Runtime top-p override. |
+| `--reasoning-effort <value>` | Runtime reasoning-effort override. |
 | `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
 
 Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
@@ -79,6 +81,18 @@ selected prompt ID must have exactly one available version. `--input` is
 optional at the CLI boundary: Promptkit decides whether the selected definition
 requires declared inputs or template-referenced values.
 
+`--session-id` supplies a direct, non-secret session identifier. A nonblank
+value replaces a definition-rendered session ID; an omitted or blank value lets
+the definition supply one. Promptkit trims direct values and limits them to 256
+Unicode code points. Use stable, non-sensitive identifiers because effective
+session IDs may appear in prepared output, run metadata, and provider-facing
+requests.
+
+`--reasoning-effort` is presence-aware: omitting it inherits the selected
+profile value, a nonblank value replaces that value, and
+`--reasoning-effort=` explicitly clears inherited reasoning. Promptkit treats
+nonblank values as provider-specific opaque strings.
+
 ## `scriptorium render`
 
 ```text
@@ -89,11 +103,13 @@ scriptorium render [flags]
 `--config`, `--prompt-dir`, `--profile-dir`, `--prompt-version`, `--profile`,
 `--input`, `--var`, `--out`, `--llm-base-url`,
 `--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
-`--timeout`, and `--format text|json`. Their meanings match the corresponding
+`--reasoning-effort`, `--session-id`, `--timeout`, and `--format text|json`. Their meanings match the corresponding
 `run` flags; `--format` selects prepared-run output and otherwise uses
 `defaults.render_format`.
 
 The same deprecated aliases and numeric/timeout behavior as `run` apply.
+The same session and reasoning inheritance, replacement, and clearing behavior
+also applies.
 `render` does not accept `--schema-dir`; configure `schema_dir` through the
 configuration file. It resolves profiles and schemas as part of preparation but
 does not call an LLM.

docs/roadmap/implementation.md

@@ -225,6 +225,8 @@ built-in, or endpoint-only execution targets.
 
 ## Stage 4: Expose Session And Presence-Aware Reasoning Controls
 
+**Completion: Complete.**
+
 Complete the request mapping for direct session identifiers and the v0.9.0
 reasoning override semantics.