From 2a086b638988d3617d1a816e9ff929fcc678ef0a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 19:48:59 +0000 Subject: [PATCH] Document shared loading and integration upgrades --- docs/cli.md | 36 +++++++----- docs/consumers/guide.md | 56 ++++++++++++------- docs/development.md | 13 +++-- docs/internal/overview.md | 4 +- docs/roadmap/implementation.md | 11 +++- integrations/ckconfig/configkit_adapter.go | 4 ++ integrations/ckconfig/doc.go | 6 ++ .../ckconfig/docs/releases/v0.10.0.md | 25 +++++++++ integrations/ckprompt/doc.go | 4 ++ .../ckprompt/docs/releases/v0.11.0.md | 40 +++++++++++++ .../ckprompt/examples/composed/README.md | 20 ++++--- 11 files changed, 170 insertions(+), 49 deletions(-) create mode 100644 integrations/ckconfig/docs/releases/v0.10.0.md create mode 100644 integrations/ckprompt/docs/releases/v0.11.0.md diff --git a/docs/cli.md b/docs/cli.md index 1f2c824..55e9c7b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -477,8 +477,8 @@ records preserve their returned order. No records are output begins with the scope heading and prints the same source fields, quoting labels and paths. These fields come from ConfigKit's source records; producing the report does not reload files or rerun version checks. See the -[ConfigKit v1.2.1 source -records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/records.go) +[ConfigKit v1.4.0 source +records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/records.go) for native evidence definitions. ### Explain a configuration path @@ -502,7 +502,12 @@ occurred in history; `--under POINTER` selects a subtree, and `--explicit=true` or `--explicit=false` filters current paths by native explicitness. Historical-only paths do not match an explicitness filter. These options require `--list`. The report contains the scope and each selected path's current presence and, -when present, its explicitness. Path discovery does not include values or history. +when present, its explicitness. Path discovery does not include values or +history. Focused scopes list their native candidates, such as paths beneath +`/promptkit`; explicit `--path` +queries use native whole-load paths, including outside the focus where supported. +A scope is not an access-control boundary. Sources and diagnostics retain the +whole load's evidence. Pointer tokens use JSON Pointer escaping: `~1` represents `/` and `~0` represents `~`. A malformed pointer is a usage error with status `2` and is @@ -599,7 +604,10 @@ concise report contains `additions`, `changes`, and `deletions`. Additions and changes keep the configuration's path structure and show right-side values from the comparison. Deletions are JSON Pointer paths. Explicit null is a value, not a deletion. Changed lists and regions replaced as a whole are shown -as whole values. +as whole values. Focused scopes render the selected subtree and compare native +views; differences at an atomic ancestor can remain in the result. An absent +focused effective value can fail output delivery, while an explicit null remains +null. ConfigKit considers sensitivity on both sides. A secret value can change even when both redacted snapshots look the same. For those ConfigKit-backed @@ -666,7 +674,7 @@ request overrides. Backend reports describe configured backend fields. An `api_key_env` value names an environment variable; it is not a credential value or a claim that one is available. Neither report resolves references or performs a network probe. See the [PromptKit resource inspection -contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/resource_inspection.go). +contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/resource_inspection.go). Omitting the ID is a usage error. Configuration loading follows the [configuration failure classification](#configuration-failure-classification); lookup failures and cancellation are operational. @@ -722,7 +730,7 @@ text output use YAML. Preparation can read resources and include rendered application content in the report. It does not guarantee that a later model call will succeed. Application loaders and callbacks may have their own effects. The [PromptKit Prepare -API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go) +API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go) owns the prepared value and upstream preparation behavior. Configuration failures follow the [configuration failure classification](#configuration-failure-classification); other preparation failures are operational. @@ -758,8 +766,8 @@ identity rather than changing the discovered requirements. An enabled profile namespace qualifies an explicitly supplied short profile ID; it does not rewrite the prompt's stored default reference. Requirements inspection does not require the selected profile to be execution-ready. See the [PromptKit -v0.23.2 consumer -guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) +v0.24.0 consumer +guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md) for configuration, selection, and requirements behavior. For built-in flags other than `--llm-var`, repeating a flag uses its last value. Application-defined flags follow their own repetition rules. @@ -870,7 +878,7 @@ applicable. It does not make a model call or retain a prepared execution snapshot. A successful report describes this preparation invocation; it does not certify provider acceptance or guarantee later execution. See PromptKit's [`Engine.ValidateRequest` -API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go). +API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go). Configuration errors returned by request construction or engine loading follow the [configuration failure classification](#configuration-failure-classification). @@ -936,8 +944,8 @@ The entries are: A catalog result is an inventory, not a readiness check or execution result. The owning provider controls membership and order. Namespace filters are passed to PromptKit without local membership interpretation. See the -[PromptKit v0.23.2 consumer -guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) +[PromptKit v0.24.0 consumer +guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md) for resource and selection definitions. Catalog loading failures follow the [configuration failure classification](#configuration-failure-classification). @@ -1108,9 +1116,9 @@ separately from delivery failures through the [reporting API](consumers/guide.md#invocation-reporting). Native configuration, selection, and diagnostic meanings remain owned by -PromptKit. See the [v0.23.2 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md), -[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/smoke_diagnostics.go), -and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go). +PromptKit. See the [v0.24.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md), +[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/smoke_diagnostics.go), +and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go). ## Outcome status diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 758915a..d686647 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -37,9 +37,11 @@ go get go.maximumdirect.net/commandkit@v0.7.0 Select either integration with `go get go.maximumdirect.net/ckconfig@v0.9.0` or `go get go.maximumdirect.net/ckprompt@v0.10.0`. Both integrations select core v0.7.0. ckprompt v0.10.0 selects ckconfig v0.9.0, which includes -`AdaptDiagnostics` and `ClassifyConfigurationError`. Both integrations build -independently against their released dependencies. An aligned workspace can -exercise the local sources together during development. +`AdaptDiagnostics` and `ClassifyConfigurationError`. Those published releases +build independently. The current checkout adopts +ConfigKit v1.4.0 and PromptKit v0.24.0; ckprompt uses the new local ckconfig API +while still requiring published ckconfig v0.9.0. Use an aligned workspace until +ckconfig is released and selected by ckprompt. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency. @@ -48,10 +50,12 @@ loaders should use keyed struct literals when constructing them. ConfigKit's release notes describe main-relative imports and overlay contexts. [ConfigKit v1.2.0 upgrade guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/releases/v1.2.0.md#upgrade-notes). -The current checkout selects PromptKit v0.23.2, which exposes main-relative -companion imports through its existing configuration-source API. Applications -select those inputs when constructing -the engine supplied to ckprompt's loader callback. [PromptKit companion import guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md#load-companion-prompts-relative-to-the-main-configuration). +The current checkout selects PromptKit v0.24.0. Complete documents put +settings under `promptkit`; wrapperless fragments use `SettingsInput`, and +collection fragments use `CollectionInput`. Consult the [upstream migration +guide](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md) +and [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md) +for the exact migration and schema rules. Importing a module does not install its commands. Pass commands to `commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's @@ -309,6 +313,14 @@ separate initialization calls do not guarantee distinct objects. See [ckconfig.Suite's GoDoc](../../integrations/ckconfig/contracts.go) for factory timing, omitted-factory zero values (including nil pointers), and ownership. The application owns the state type and what it caches. +`ckconfig.FromConfigKitSubtree(name, summary, path, load)` adapts the same typed +loader to a focused native inspection. The loader validates the whole result; +its sources and findings retain whole-load context. Listing uses the focused +native paths, while explicit paths and comparison retain native semantics. The +[composed example](../../integrations/ckprompt/examples/composed/main.go) uses +this adapter for `storage` and passes the same application result to +`promptkit.NewFromConfig`. The application composes `promptkit.Configure` and +selects `BundledOpenRouterUnderlay` before loading when it needs that catalog. `ckconfig.FromConfigKit` adapts a typed ConfigKit loader without calling it during construction. The bundled comparison adapters call the loader for the left side before the right, retain left diagnostics if right loading fails, @@ -320,8 +332,10 @@ The `config` family provides scope discovery, validation, safe effective configu source inventory, path explanation, and ConfigKit-backed comparison for the capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes) owns operator syntax and report details. `Scope.Features` declares optional modes; acquired -`View.Metadata` and `View.Findings` carry native path metadata and diagnostic -records when available. `Findings.Messages` contains presentations associated +`View.Paths` supplies native discovery candidates; when nil, `View.Metadata` +supplies them for existing custom providers. Metadata remains required for +filtering and describing candidates. `View.Findings` carries diagnostic records +when available. `Findings.Messages` contains presentations associated with those records, while `Acquired.Diagnostics` carries independent messages. Custom explanation providers implement `Explain`; CommandKit renders the acquired evidence. See `EffectiveWriter` and `ExplanationReader` in the @@ -343,8 +357,8 @@ parses CLI records but cannot add them to an already-loaded result. The engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose it under `config` with validate/show/sources/explain and native diff operations; it does not install PromptKit catalog, definition, or requirements commands. -Its override feature is disabled because the released PromptKit configuration -loader does not accept ConfigKit override records. +Its override feature is disabled by default. Applications may enable it only +when their own loader applies the supplied overrides. ### Install resource commands and optional checks @@ -388,7 +402,9 @@ If the loader is nil, the returned suite retains a wiring issue for installation to report, even if capabilities are narrowed later. A builder runs before the engine loader and receives the seed request, selection, typed input, shared state, and invocation context. It returns the -concrete request; the adapter does not merge seed fields back afterward. The +concrete request; the adapter does not merge seed fields back afterward. For +validation replacements use `*promptkit.OutputContractInput`: a nil repair +budget remains omitted and a pointer to zero explicitly disables repair. The loader receives the original selection. Builders should start from the seed, preserve operator values and bindings, and apply defaults only when a map key is absent, so explicitly supplied empty values stay meaningful. Applications that @@ -424,7 +440,7 @@ and uses `Engine.ValidateRequest`. Applications own engine construction and may build complete native requests in callbacks. Preparation and validation use the supplied context; execution owns prepared notifications and operation timeouts. See the [PromptKit consumer -guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) +guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md) for conversation and execution capabilities. `ckprompt.WithRequestPreparation` adds a separate callback backed by @@ -463,7 +479,7 @@ complete return value is authoritative. The [CLI reference](../cli.md#promptkit- and reports. The [composed example](../../integrations/ckprompt/examples/composed/README.md) -combines app and PromptKit config scopes, comparison and catalogs, named and +combines app, storage, and PromptKit config scopes, comparison and catalogs, named and requirements inspection, request validation, smoke testing, and an application-owned `session restore` command. @@ -487,7 +503,7 @@ These are independent defaults for unqualified caller-supplied prompt, profile, and backend names; qualified IDs pass through. Stored references and configuration inspection are unchanged, while namespace and collection inventories remain global. Catalog `--namespace` filters are separate from these defaults. See the released -[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/namespaces.go). +[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/namespaces.go). ## Outcomes and ownership @@ -501,8 +517,8 @@ signal handling, and exit mapping; `Execute` never exits the process. Go declarations and GoDoc own exact exported contracts. ConfigKit owns configuration decoding, validation, and provenance. PromptKit owns prompt formats, profile resolution, and inspection details. See the -[ConfigKit v1.2.1 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/records.go), -[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/engine.go), -[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/configuration_inspection.go), -[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/smoke_diagnostics.go), -and [PromptKit v0.23.2 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md). +[ConfigKit v1.4.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/records.go), +[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/engine.go), +[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/configuration_inspection.go), +[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/smoke_diagnostics.go), +and [PromptKit v0.24.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/docs/consumers/pkg-promptkit.md). diff --git a/docs/development.md b/docs/development.md index 15f13cf..655968b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -119,11 +119,14 @@ If a workspace already exists, ensure it includes these three modules. Preserve the ignored `go.work` and `go.work.sum`; do not commit them. Use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation and independent module suites. Both integrations select released core v0.7.0; -ckprompt also selects released ckconfig v0.9.0. Both integrations support -independent builds against their published dependencies. The aligned workspace -exercises the local sources together. -Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module -directory. From the repository root, a workspace containing all three modules can also run: +ckprompt currently selects released ckconfig v0.9.0 but uses the new local +ckconfig API. Until the coordinated release, isolated validation uses a temporary +local replacement as described in the [implementation plan](roadmap/implementation.md#stage-7-validate-the-result-and-record-release-coordination); +the independent suite against published requirements remains pending. +The aligned workspace exercises local sources together. Run the independent +suites for core and ckconfig with `GOWORK=off GOTOOLCHAIN=local go test ./...` +from each module directory. From the repository root, a workspace containing +all three modules can also run: ```sh GOTOOLCHAIN=local go test ./... diff --git a/docs/internal/overview.md b/docs/internal/overview.md index dfc31ec..ad51deb 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -91,7 +91,9 @@ Cobra and pflag imports remain inside this package. `integrations/ckconfig` owns ConfigKit adaptation, scope capture, the standard `config` command family, and native validate/show/sources/explain/diff behavior. It depends on the public core facade and ConfigKit; it does not depend on -PromptKit. Each selected scope or comparison side receives an independently +PromptKit. Whole-result and subtree scopes share loader and diagnostic adaptation; +subtree scopes delegate focused path enumeration and comparison to native +ConfigKit inspection. Each selected scope or comparison side receives an independently initialized input, while one suite-owned state value is shared by an invocation's acquisitions or comparison callback. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 86dd7a0..de6d7bb 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -316,7 +316,16 @@ result for corresponding selections, and comparison sides remain independent. ## Stage 6: Update canonical guidance and candidate release notes -Status: pending. +Status: complete. + +Evidence: Updated GoDoc, CLI, consumer, development, internal, and composed +example guidance, plus candidate notes for ckconfig v0.10.0 and ckprompt +v0.11.0. Neither candidate tag exists locally or on `origin`. Reviewed selected +module graphs and upstream license material; affected attribution was updated +in Stage 1 and no transitive version changed. Local Markdown links and fragments +passed a repository link check, `git diff --check` passed, and the ckprompt +workspace suite including the example passed with Go 1.27.4. Publication and +the ckprompt released-dependency update remain pending. 1. Finish exported GoDoc and package guidance in both integrations. Document `View.Paths` precedence and metadata fallback, the subtree helper signature, diff --git a/integrations/ckconfig/configkit_adapter.go b/integrations/ckconfig/configkit_adapter.go index e0326a2..7bdcb25 100644 --- a/integrations/ckconfig/configkit_adapter.go +++ b/integrations/ckconfig/configkit_adapter.go @@ -61,6 +61,10 @@ func FromConfigKit[I, S, T any]( // Discovery and rendering use the focused inspection, while explicit paths and // comparison retain ConfigKit's native semantics. Construction and help do not // load configuration, and a nil loader is recorded as a construction issue. +// The loader receives each operation's selection, input, and shared state. +// A valid absent subtree can be acquired, but rendering its effective value +// reports the native unavailable-value error. An unavailable inspection returns +// an operational error with any whole-load evidence already acquired. func FromConfigKitSubtree[I, S, T any]( name, summary string, path configkit.Path, diff --git a/integrations/ckconfig/doc.go b/integrations/ckconfig/doc.go index c50decb..883e7f8 100644 --- a/integrations/ckconfig/doc.go +++ b/integrations/ckconfig/doc.go @@ -4,6 +4,12 @@ // Use AppCommand for one application configuration loader, or Command with a // Suite for multiple named configurations and application-specific flags. // Install the returned command with commandkit.New or App.Register. +// +// FromConfigKitSubtree adapts an ordinary typed loader and native path to a +// focused scope, retaining whole-load sources, findings, and validation. +// View.Paths selects native listing candidates; nil falls back to Metadata. +// Explicit paths and comparison retain upstream semantics. +// // Importing this package alone installs no commands. // // ConfigKit owns configuration loading and interpretation. CommandKit formats diff --git a/integrations/ckconfig/docs/releases/v0.10.0.md b/integrations/ckconfig/docs/releases/v0.10.0.md new file mode 100644 index 0000000..1498972 --- /dev/null +++ b/integrations/ckconfig/docs/releases/v0.10.0.md @@ -0,0 +1,25 @@ +# CommandKit ckconfig v0.10.0 + +Candidate note; publication is pending. + +CommandKit ckconfig v0.10.0 adopts ConfigKit v1.4.0 and adds native focused +configuration scopes. It continues to select CommandKit core v0.7.0 and Go +1.27.0 as the consumer minimum. + +## Compatibility and upgrade + +`FromConfigKitSubtree` adapts an application-owned typed result loader and a +ConfigKit path to the standard scope operations. Loading and validation cover +the whole result; focused output and comparison use native inspection while +sources and diagnostics retain whole-load context. See the +[consumer guide](../../../../docs/consumers/guide.md#configkit-scopes) and +[ConfigKit v1.4.0 notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md). + +`View.Paths` optionally supplies native path-discovery candidates. When it is +nil, existing custom scopes continue to enumerate `View.Metadata`; metadata +still describes and filters candidates. The added exported field can break +positional `View` literals. Convert them to keyed literals before upgrading. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/COPYRIGHT) | +[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/LICENSE) | +[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/docs/oss/attribution.md) diff --git a/integrations/ckprompt/doc.go b/integrations/ckprompt/doc.go index 8ac4552..31a89b0 100644 --- a/integrations/ckprompt/doc.go +++ b/integrations/ckprompt/doc.go @@ -8,6 +8,10 @@ // these with commandkit.New or App.Register. // // ConfigScope separately exposes engine configuration through ckconfig. +// ConfigScope preserves PromptKit focused discovery and whole-load evidence. +// Applications can compose PromptKit settings into an application-owned load +// and pass the completed result to promptkit.NewFromConfig. +// // Importing this package installs neither command family. Applications own // engine construction, credentials, and client configuration. package ckprompt diff --git a/integrations/ckprompt/docs/releases/v0.11.0.md b/integrations/ckprompt/docs/releases/v0.11.0.md new file mode 100644 index 0000000..c4c583f --- /dev/null +++ b/integrations/ckprompt/docs/releases/v0.11.0.md @@ -0,0 +1,40 @@ +# CommandKit ckprompt v0.11.0 + +Candidate note; publication is pending. + +CommandKit ckprompt v0.11.0 adopts PromptKit v0.24.0 and ConfigKit v1.4.0. +It supports application-owned shared configuration loading and exposes native +focused PromptKit inspection. Core remains v0.7.0 and the consumer minimum +remains Go 1.27.0. + +## Compatibility and upgrade + +Pair this release with the coordinated ckconfig release. Complete PromptKit +configuration documents now place settings under `promptkit`; mount wrapperless +settings with `SettingsInput` and collection fragments with `CollectionInput`. +Discovery inputs for fragments need an explicit destination. Resource IDs do +not gain a prefix, but configuration paths now use native locations such as +`/promptkit/profiles/0/model`. Focused listings use native paths; explicit +queries, sources, diagnostics, and comparison retain whole-load context. + +PromptKit removed `Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile`. +Use supported inline, source-relative, or explicit-root schema selection. +Request builders replace validation with `*promptkit.OutputContractInput`; +its pointer repair budget distinguishes omission from explicit zero. Resolved +reports include the budget, including zero, and prompt reports include native +schema selections. The default enables one repair for eligible modes, which +can add a generation call, latency, and usage. Applications own resource-version +policy and sensitivity of their extension fields. + +Prepared reports now include `message_content_hash` and native schema evidence. +Migrate positional `PreparedRun` literals to keyed fields; older JSON without +the hash decodes with an empty hash. See the [PromptKit migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md), +[format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md), +and [release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md) +for the upstream contract. PromptKit v0.23.3's timeout and cancellation identity +corrections are included. The [consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements) +links the maintained shared-load example. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/COPYRIGHT) | +[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/LICENSE) | +[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/docs/oss/attribution.md) diff --git a/integrations/ckprompt/examples/composed/README.md b/integrations/ckprompt/examples/composed/README.md index be30e71..dadf0e8 100644 --- a/integrations/ckprompt/examples/composed/README.md +++ b/integrations/ckprompt/examples/composed/README.md @@ -6,8 +6,8 @@ in-memory model client. **No model service or credentials are required.** Use Go 1.27.0 on `PATH`. An aligned workspace containing all three local modules exercises their current sources; follow the [workspace setup](../../../../docs/development.md#documentation-validation) -from the repository root. The example also builds independently with -`GOWORK=off` against its module's released dependencies. +from the repository root. The current checkout requires the local ckconfig API; +its published v0.9.0 dependency does not yet provide that API. The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns version and compatibility details. @@ -21,7 +21,7 @@ go run . promptkit list prompts --campaign spring go run . promptkit show prompt briefing --campaign spring --format yaml ``` -The first command lists `app` and `promptkit` configurations and their available +The first command lists `app`, `storage`, and `promptkit` configurations and their available operations. The next commands find and inspect the `briefing` prompt. `--campaign` is a selector supplied by this example, not a standard PromptKit flag. @@ -30,6 +30,8 @@ operations. The next commands find and inspect the `briefing` prompt. ```sh go run . config validate --scope all --campaign spring --limit=0 go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml +go run . config show --scope storage --config fixtures/before.yml +go run . config diff --scope storage --config fixtures/before.yml --against-config fixtures/after.yml go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --against-campaign spring ``` @@ -44,8 +46,8 @@ The two sides have independent selectors and overrides: go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details ``` -Only the application scope supports `--set` here. The released PromptKit loader -has no override handoff, so its configuration scope does not enable the feature. +The application and storage scopes support `--set` here. The PromptKit scope +does not advertise override support in this example. An aggregate operation that includes that scope rejects overrides. ## List resources and select namespaces @@ -155,7 +157,9 @@ selects the command context without loading an engine. The example installs `ckconfig.Command(suite)` and `ckprompt.Declarations(definitions)` with application-owned aliases in a `[]commandkit.Declaration`. `NewInput` initializes scope inputs; `NewState` -creates a cache shared within an invocation. The loaders cache successful +creates a cache shared within an invocation. The application composes PromptKit +settings and resources into its ConfigKit load; the engine consumes the same +result, and `FromConfigKitSubtree` exposes `storage`. The loaders cache successful configuration results by the complete configuration/overlay selection, overrides, and supplied campaign, including whether each value was supplied. These are example choices, not a CommandKit cache policy. @@ -167,5 +171,5 @@ for suite composition, builders, and ownership, and the [source](main.go) for the complete application. Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory -for an aligned workspace check. Use -`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases. +for an aligned workspace check. Independent ckprompt validation against its +declared requirements follows the coordinated ckconfig release.