Document profile and prompt identity listings

doc.go

@@ -4,15 +4,16 @@
 // Applications construct an [Engine] with [NewEngine], select ConfigKit
 // sources for prompts, profiles, and backends, and
 // call [Engine.InspectConfiguration], [Engine.InspectPrompt],
-// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.Prepare],
+// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.ListProfiles],
-// [Engine.PrepareExecution], [Engine.Run], or [Engine.RunPrepared]. Concrete
+// [Engine.ListPrompts], [Engine.Prepare], [Engine.PrepareExecution],
-// registries, repositories, validators, and the built-in OpenAI-compatible
+// [Engine.Run], or [Engine.RunPrepared]. Concrete registries, repositories,
-// client remain internal implementation details.
+// validators, and the built-in OpenAI-compatible client remain internal
+// implementation details.
 //
 // # Concurrency and ownership
 //
 // An Engine supports concurrent InspectConfiguration, InspectPrompt,
-// InspectRequirements, InspectProfile, Prepare,
+// InspectRequirements, InspectProfile, ListProfiles, ListPrompts, Prepare,
 // PrepareExecution, Run, and RunPrepared calls. Engine-local backend policies
 // bound admitted Run and RunPrepared calls and model generations where
 // configured, while different backend pools and unlimited backends continue
@@ -23,6 +24,7 @@
 // Engine. Prepare, PrepareExecution, and Run copy request maps, slices, pointer
 // values, and JSON-compatible extra parameters before using them. InspectPrompt,
 // InspectRequirements, and InspectProfile return copied inspection values.
+// ListProfiles and ListPrompts return caller-owned identity slices.
 // Returned values and values passed to extension interfaces are likewise
 // isolated from engine state.
 // Callers own those copies and may mutate them after the call that supplied or
@@ -58,8 +60,8 @@
 // [ConfigurationSources], [ConfigurationInspection], [BackendConfig],
 // [ProfileConfig], [RunRequest],
 // [ArtifactRef], [ExecutionTargetOverride], [ProfileInspection],
-// [PromptInputDefinition], [PromptInspection], [RequirementInspectionRequest],
+// [PromptIdentity], [PromptInputDefinition], [PromptInspection],
-// [RequirementInspection], [PreparedExecution],
+// [RequirementInspectionRequest], [RequirementInspection], [PreparedExecution],
 // [CapacityError], [GenerationError], [RetryExhaustedError], and
 // [ExecutionEvent], do not have stable JSON
 // representations. Direct API keys are nevertheless excluded from JSON for

docs/consumers/pkg-promptkit.md

@@ -118,6 +118,43 @@ engines and prepared handles retain their captured definitions; schema and
 request artifact resources still follow their runtime lifecycle. Inspection
 does not watch or reload sources automatically.
 
+## Discover Available Profiles And Prompts
+
+Use [`Engine.ListProfiles`](../../listing.go) and
+[`Engine.ListPrompts`](../../listing.go) to discover exact identities from the
+engine's final captured configuration, then inspect a selected prompt:
+
+```go
+profiles, err := engine.ListProfiles(ctx)
+if err != nil {
+	return err
+}
+if len(profiles) > 0 {
+	_, err := engine.InspectProfile(ctx, profiles[0])
+	if err != nil {
+		return err
+	}
+}
+prompts, err := engine.ListPrompts(ctx)
+if err != nil {
+	return err
+}
+if len(prompts) > 0 {
+	selected := prompts[0]
+	inspection, err := engine.InspectPrompt(ctx, selected.ID, selected.Version)
+	if err != nil {
+		return err
+	}
+	_ = inspection
+}
+```
+
+These lists describe effective membership, not ConfigKit contribution history,
+and do not promise that a profile is ready to execute. Use inspection for
+details and preparation to resolve request resources. The linked method GoDoc
+owns ordering, ownership, concurrency, and error behavior; identifiers may be
+sensitive application data.
+
 ## Inspect The Captured Configuration
 
 Use [`Engine.InspectConfiguration`](../../configuration_inspection.go) for an

docs/formats.md

@@ -51,7 +51,8 @@ message files on ordinary runs; construct a new engine to observe edits.
 Schema and request artifact reads still happen during preparation. Use
 `InspectConfiguration` for an explicit effective-configuration or provenance
 report, `InspectProfile` for backend-completed profile settings, and preparation
-for request-specific rendered details.
+for request-specific rendered details. For identity discovery before inspection,
+see the consumer guide's [profile and prompt listing](consumers/pkg-promptkit.md#discover-available-profiles-and-prompts).
 
 ## Prompt Definitions
 

docs/internal/overview.md

@@ -11,16 +11,16 @@ contributor workflow and validation.
 
 | Component | Implemented responsibility | References |
 | --- | --- | --- |
-| Root `promptkit` package | Provides the supported engine facade, ConfigKit source helpers, profile and backend mapping conveniences, injection options, public requests and results, prompt/profile/requirement inspection, observation values, opaque prepared-execution handles, value conversion, redacted formatting, and typed capacity and generation error mapping. | [Package GoDoc](../../doc.go), [observations](../../observations.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine facade](../../engine.go), [requirement facade](../../requirements.go) |
+| Root `promptkit` package | Provides the supported engine facade, ConfigKit source helpers, profile and backend mapping conveniences, injection options, public requests and results, prompt/profile/requirement inspection and identity listing, observation values, opaque prepared-execution handles, value conversion, redacted formatting, and typed capacity and generation error mapping. | [Package GoDoc](../../doc.go), [observations](../../observations.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine facade](../../engine.go), [identity listing](../../listing.go), [requirement facade](../../requirements.go) |
 | `examples/go-library/prepare` | Demonstrates offline preparation and explicit configuration inspection with a prompt file, programmatic profile, and inline input. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) |
 | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, programmatic profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
 | `examples/go-library/observe` | Demonstrates offline built-in HTTP retry and synchronous metadata observation across structured proposal and assessment runs using embedded sources, two profiles on one finite backend, and an application decision. It is not a public library package. | [Example program](../../examples/go-library/observe/main.go) |
 | `internal/backend` | Holds a defensive, immutable lookup and capacity-policy index for final backend definitions validated by the configuration adapter. | [Backend registry](../../internal/backend/registry.go) |
 | `internal/catalog` | Selects released keyed catalog assets and PromptKit-owned profile definitions as ConfigKit underlays; effective validation belongs to the configuration loader. | [Catalog adapter](../../internal/catalog/catalog.go), [internal sources](sources.md#profiles-and-built-ins) |
-| `internal/configuration` | Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values, captures indexed prompt definitions, referenced message content, compiled templates, and input metadata snapshots, constructs backend and presence-aware profile snapshots, and retains an explicit read-only inspection view. | [Typed loader](../../internal/configuration/load.go), [internal sources](sources.md#typed-configuration-loading) |
+| `internal/configuration` | Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values, captures indexed prompt definitions, referenced message content, compiled templates, input metadata snapshots, sorted identity-only profile and prompt inventories, backend and presence-aware profile snapshots, and an explicit read-only inspection view. | [Typed loader](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
 | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) |
 | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) |
-| `internal/engine` | Assembles selected catalog and caller configuration into one snapshot, then constructs capacity, rendering, validation, generation, repair, and the use-case runner for each engine. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#profiles-and-built-ins), [internal runner](runner.md) |
+| `internal/engine` | Assembles selected catalog and caller configuration into one snapshot, then constructs capacity, rendering, validation, generation, repair, and the use-case runner for each engine. It delegates identity listing directly to the captured configuration inventory rather than the runner. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#profiles-and-built-ins), [internal runner](runner.md) |
 | `internal/generation` | Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, and attempt observations. | [Internal generation coordination](generation.md) |
 | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
 | `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |

docs/internal/sources.md

@@ -21,6 +21,11 @@ profile inheritance. It retains ConfigKit's result privately for explicit
 inspection, not for per-run resolution. The runtime/domain packages do not
 depend on ConfigKit.
 
+After prompt materialization and effective-profile snapshot construction, the
+adapter captures lexically ordered, identity-only inventories from the final
+prompt and indexed-profile maps. Its listing methods return caller-owned copies
+of those inventories without consulting ConfigKit or copying definitions.
+
 The root `DirectoryInputs` and `FilesystemInputs` helpers discover sorted YAML
 files under an explicit root, provide resource context, and leave imports
 disabled. Each returned slice belongs to one strict-composition group; file
@@ -119,6 +124,10 @@ profile without copying its target or requiring readiness. The
 target interpretation, while the [catalog tests](../../internal/catalog/catalog_test.go)
 cover selected released assets.
 
+The internal engine delegates listing through a narrow identity-inventory
+interface directly to the configuration snapshot. The execution runner has no
+listing responsibility.
+
 ## Ordinary Artifacts
 
 `internal/artifact` accepts explicitly typed inline references even when their

docs/roadmap/implementation.md

@@ -2,7 +2,7 @@
 
 Implement the [listing roadmap](listing.md) in the numbered order below.
 Each stage is scoped for one Luna coding-agent prompt and should leave a
-compiling, tested unit. All four stages are pending.
+compiling, tested unit. All four stages are complete.
 
 This replaces the completed performance plan, preserved in
 [Git history](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md).
@@ -216,7 +216,11 @@ independent results, concurrent safety, and listing without execution work.
 
 ## Stage 4 — Document And Verify The Completed Feature
 
-**Status: Pending.** Depends on Stage 3.
+**Status: Complete (2026-10-09).** Verified with the full offline race suite,
+repository-wide vet, maintained consumer examples, changed documentation-link
+checks, and `git diff --check`. The listing roadmap and canonical consumer,
+format, and internal documentation now describe the implemented API. Depends
+on Stage 3.
 
 **Scope:** owning documentation, final review, and complete offline verification.
 

docs/roadmap/inspection.md

@@ -1,7 +1,7 @@
 # Effective Prompt Requirement Inspection
 
 Status: Implemented (2026-10-08). The
-[implementation plan](implementation.md) records the completed work units and
+[inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md) records the completed work units and
 final verification. Current public API details live in GoDoc; the consumer
 guide, format reference, and internal documents link to those canonical
 contracts.
@@ -194,7 +194,7 @@ template syntax and effective metadata; inspection does not enter artifact,
 schema, credential, rendering, provider, or execution preparation.
 
 The final verification and the commit sequence are recorded in the
-[implementation plan](implementation.md). The exact public contract is owned by
+[inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md). The exact public contract is owned by
 [GoDoc](../../requirements.go); consumer usage, framework-format cross-reference,
 and internal selection/source descriptions are maintained in their respective
 documents.

docs/roadmap/listing.md

@@ -1,6 +1,8 @@
 # Profile And Prompt Listing
 
-Status: Accepted; implementation pending.
+Status: Implemented (2026-10-09). All public listing behavior and verification
+are complete; see the [implementation plan](implementation.md) for completion
+and verification evidence.
 
 ## Purpose
 
@@ -10,8 +12,8 @@ history. This supports application selectors, CLI discovery, and configuration
 editors while keeping PromptKit's public API small.
 
 Listing supplies identities; the existing inspection methods supply details.
-The [implementation plan](implementation.md) defines staged work. This roadmap
+The [implementation plan](implementation.md) records the completed work. This
-describes the intended feature, not currently available methods.
+roadmap captures feature scope; the public GoDoc owns the current API behavior.
 
 ## Current Baseline
 

docs/roadmap/performance.md

@@ -3,7 +3,7 @@
 Status: Complete (2026-10-09). The ConfigKit request (item 1) was submitted,
 and local items 2–7 were implemented or completed with the evidence and
 conditional ownership decision recorded in the
-[implementation plan](implementation.md). No dependency upgrade or public
+[performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md). No dependency upgrade or public
 performance guarantee was part of this work.
 
 ## Purpose
@@ -14,7 +14,7 @@ library use make redundant full-payload copies especially worth addressing.
 Prefer small, idiomatic improvements over additional framework machinery.
 
 This roadmap captures the intended outcomes and recommended changes. The
-[implementation plan](implementation.md) owns staged work and verification.
+[performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md) owns staged work and verification.
 This roadmap introduces no new public performance guarantee. Existing contracts
 remain owned by GoDoc, the
 [format reference](../formats.md), and the

docs/roadmap/remediation.md

@@ -5,7 +5,7 @@ Status: All recorded findings have been resolved in separate remediation units.
 ## Computational Efficiency Review
 
 Review baseline: `8a5c0de`, compared with planning commit `3fde1f6`, the
-[performance roadmap](performance.md), and [implementation plan](implementation.md).
+[performance roadmap](performance.md), and [performance implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7325a34c070c77c4784ab76c916fc8a4d79b5c46/docs/roadmap/implementation.md).
 
 ### Finding 1 — Release A Stale File Reservation For An Empty Body (P3)
 
@@ -59,7 +59,7 @@ gaps or strengthened public contracts were identified in this review.
 
 Review baseline: `a051edd82d9d20cdc82dfebf25adb689dc58b01f`.
 Scope: implementation commits after `a6e0ffe`, compared with the simplified
-[feature roadmap](inspection.md) and [implementation plan](implementation.md).
+[feature roadmap](inspection.md) and [inspection implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/481e2d494c5a4e8b7f3a2a6f1cceaeb3f7c71d05/docs/roadmap/implementation.md).
 The existing ReleaseKit documentation finding is retained below.
 
 ### Finding 1 — Report Lost Caller-Map Scope As Incomplete (P2)