Correct inspection framing and callback ownership documentation

docs/cli.md

@@ -145,9 +145,11 @@ example config show --scope all
 
 `--scope all` acquires every selected scope and checks each effective writer
 before writing output. It then emits one YAML document per scope in discovery
-order, with a `# scope: NAME` comment after each document marker. Existing native
-markers and leading comments are retained; documents without a marker receive
-one. Scope labels containing line control characters are quoted to keep them on
+order, with a `# scope: NAME` comment at each document boundary. For ordinary
+block documents the comment follows the marker. When a native opening marker
+contains inline content, the comment precedes that marker so it does not
+interrupt the native value. Existing native markers and leading comments are
+retained; documents without a marker receive one. Scope labels containing line control characters are quoted to keep them on
 one comment line. A provider failure leaves the output stream empty. A rendering
 or output failure may leave an aggregate prefix, and the outcome reports
 incomplete report delivery.
@@ -228,11 +230,17 @@ serialized as `[]`.
 ## PromptKit definition inspection
 
 Applications can install prompt and profile inspection independently with
-`RegisterPromptKit`. Each installed handler constructs the selected engine once
-and asks PromptKit to inspect the named definition. Inspection reads the
-engine's captured configuration; it does not generate a prompt, contact a
-provider, or look up credentials.
-Prompt definitions and profile resolution remain owned by
+`RegisterPromptKit`. Each installed handler invokes its registered inspection
+callback once with the caller's selection and context. The bundled
+`NewPromptKitSuite` helper acquires an engine through the application loader and
+asks PromptKit to inspect its captured named definition. The loader can construct
+or reuse an engine; direct suite callbacks retain their own implementation and
+lifecycle.
+
+CommandKit's inspection path does not execute prompts, contact model providers,
+or resolve provider credential values. Application acquisition and direct
+callback effects remain application-owned. Prompt definitions and profile
+resolution remain owned by
 [PromptKit's inspection API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go).
 
 ```text
@@ -292,8 +300,11 @@ api_key_required: true
 ```
 
 Text uses labeled fields and includes nested `extra_params` values. A missing ID
-is a usage error. Blank, unknown, ambiguous, and canceled selections are
-operational inspection results from PromptKit and retain its error identity.
+is a usage error. Blank, unknown, and ambiguous definition selections reach the
+owning inspection API and produce operational results with supported public
+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.
 
 ## Outcome status
 

docs/roadmap/remediation.md

@@ -152,20 +152,22 @@ Owners: [initial.md](initial.md) and [implementation.md](implementation.md).
 
 Owner: [cli.md](../cli.md).
 
-- [ ] Correct aggregate YAML framing prose: scope comments can precede an inline
+- [x] Correct aggregate YAML framing prose: scope comments can precede an inline
   document-start marker; they are not always after the marker. Preserve the
   native content and one YAML document per scope.
-- [ ] Qualify engine acquisition/construction wording. Standard handlers invoke
+- [x] Qualify engine acquisition/construction wording. Standard handlers invoke
   registered inspection callbacks; the bundled helper acquires an engine through
   the application loader. Direct callbacks retain their own implementation and
   lifecycle rather than guaranteeing fresh engine construction.
-- [ ] Describe the absence of execution/provider/credential operations as the
+- [x] Describe the absence of execution/provider/credential operations as the
   behavior of CommandKit's inspection path, preserving application callback
   ownership of its effects.
-- [ ] Correct cancellation attribution: cancellation can be detected at
+- [x] Correct cancellation attribution: cancellation can be detected at
   CommandKit's standard-handler boundaries as well as returned by PromptKit.
   Preserve supported error identity and operational classification.
 
+**Completion:** Corrected native marker/comment placement, qualified callback and engine lifecycle claims, and reconciled cancellation attribution.
+
 ## D-08: remove stale policy status statements
 
 Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md).