Resolve public documentation contract questions

docs/roadmap/documentation.md

@@ -0,0 +1,250 @@
+# Documentation Hardening Roadmap
+
+## Purpose
+
+This roadmap coordinates a focused pass over Promptkit's documentation and
+public contract. The work should close the gaps identified by the documentation
+audit, strengthen canonical ownership, and leave consumers and contributors
+with guidance that is accurate, navigable, and proportionate to their needs.
+
+This is planning material, not a description of implemented behavior. Follow
+the [documentation policy](../policy/documentation.md) throughout the work and
+update current-state documents only when their claims are supported by the
+implementation and tests.
+
+## Scope And Principles
+
+The work covers public GoDoc, consumer guidance, maintained examples, format
+and integration references, architecture ownership, roadmap lifecycle, and
+documentation validation.
+
+- Resolve ambiguous behavior before documenting it as a contract.
+- Keep exact exported API semantics in Go declarations and GoDoc.
+- Keep task-oriented guidance in consumer documents and complete runnable
+  artifacts in `examples/`.
+- Put security-relevant consumer responsibilities at the public boundary, not
+  only in internal contributor documents.
+- Remove duplicated ownership instead of synchronizing parallel references.
+- Make documentation checks reproducible where practical.
+- Preserve existing behavior unless a stage explicitly selects and tests an
+  API change.
+
+The roadmap does not add new Promptkit features, redesign framework formats,
+or implement ideas from [the future feature catalog](future.md). If resolving
+an ambiguity requires a behavioral change, treat that change as a separately
+reviewable implementation unit and update its canonical documentation in the
+same unit.
+
+## Stage 1: Resolve Public Contract Questions
+
+Before expanding prose, decide the intended contract for exported behavior
+that is currently ambiguous.
+
+- [x] Decide whether `RunRequest.Metadata` has a supported observable purpose.
+  Define its propagation and ownership, or remove or deprecate it through an
+  intentional public API change.
+- [x] Decide and test whether one `Engine` supports concurrent `Prepare` and
+  `Run` calls.
+- [x] Decide how repeated options of the same category behave, including
+  prompt, profile, schema, model-client, and artifact-reader options.
+- [x] Define which public values have supported JSON representations.
+- [x] Define JSON time units and omission behavior, including the relationship
+  between prepared-run and run-result durations.
+- [x] Decide whether run IDs and exposed hashes have stable formats or must be
+  treated as opaque values.
+- [x] Confirm the intended transport-timeout default and its zero or negative
+  configuration semantics.
+- [x] Confirm the supported JSON Schema dialect and reference boundaries,
+  including whether remote references are allowed.
+
+The resolved contract is:
+
+- `RunRequest.Metadata` had no observable purpose and has been removed from the
+  public and internal request values.
+- One engine supports overlapping `Prepare` and `Run` calls. Built-in
+  collaborators satisfy that contract; injected collaborators may be called
+  concurrently and therefore share responsibility for concurrency safety.
+- Options are applied in order. Within each prompt-source, profile-source,
+  in-memory-profile, schema-source, model-client, or artifact-reader category,
+  the last non-nil valid option replaces the earlier value for that category.
+  An invalid earlier option still makes construction fail.
+- The supported JSON values are `PreparedRun`, `RunResult`, `Artifact`,
+  `ExecutionTarget`, `OutputContract`, `ValidationResult`, `TokenUsage`,
+  `RenderedPrompt`, `RenderedMessage`, `CacheControl`,
+  `StructuredOutputSpec`, `StructuredOutputJSONSpec`, `GenerateRequest`,
+  `GenerateResponse`, `ExecutionTargetPresence`, and the public string value
+  types used by them. Construction inputs such as `Config`, `RunRequest`,
+  `ArtifactRef`, `ExecutionTargetOverride`, `Profile`, and
+  `OpenAICompatibleProfileConfig` do not have stable JSON representations.
+  Request-scoped API keys remain excluded from JSON as a security guarantee,
+  including on otherwise unsupported construction values.
+- JSON timestamps use `time.Time`'s RFC 3339 representation and are omitted
+  when zero. Both prepared and completed run durations use integer
+  milliseconds in `duration_ms` and are omitted when zero. A prepared duration
+  measures preparation only; a run-result duration measures the complete run,
+  including its preparation, generation, and validation.
+- Run IDs, prompt hashes, rendered-prompt hashes, input hashes, and artifact
+  hashes are non-empty correlation or equality values where produced. Their
+  spelling, length, character set, and algorithm are opaque and not stable
+  formats.
+- The built-in transport timeout defaults to 10 minutes. A zero or negative
+  `Config.Timeout` selects that default. A supplied HTTP client's positive
+  timeout takes precedence; its zero or negative timeout inherits the positive
+  configured timeout or the default. These transport semantics are independent
+  of caller cancellation and per-generation timeout settings.
+- JSON Schema uses Draft 2020-12; omission of `$schema` selects that dialect
+  and an explicit different dialect is rejected. Same-document fragment
+  references are supported. Relative references may load other schema
+  documents only within a configured directory or `fs.FS` schema root.
+  A single-file schema source supports only references contained in that
+  document. Absolute, escaping, and remote references are not allowed.
+
+**Gate:** Each question has an explicit answer backed by existing behavior or
+by an accepted implementation change and proportionate tests. No later stage
+should invent a contract merely to fill a documentation gap.
+
+## Stage 2: Make GoDoc The Canonical Public Contract
+
+Strengthen the root package declarations so `go doc` is sufficient to
+understand exact public behavior without relying on internal documents.
+
+- [ ] Add useful field-level GoDoc to configuration, request, profile,
+  execution-target, result, artifact, validation, structured-output, and model
+  client values.
+- [ ] Document required fields and nil, empty, and zero-value semantics.
+- [ ] Document override, replacement, profile-precedence, and copy-ownership
+  behavior where it belongs to the exported API.
+- [ ] Document credential inputs, redaction, and the values intentionally
+  excluded from serialization.
+- [ ] Give each public error sentinel an accurate comment and document the
+  supported `errors.Is` relationships.
+- [ ] Document engine concurrency and option-composition behavior selected in
+  Stage 1.
+- [ ] Document serialization, time, run-ID, and hash semantics selected in
+  Stage 1.
+- [ ] Review constructor, option, extension-interface, `Prepare`, and `Run`
+  GoDoc for complete failure and cancellation expectations.
+
+Update the [consumer guide](../consumers/pkg-promptkit.md) to summarize and link
+to these contracts instead of maintaining exhaustive copies of exported names
+or exact semantics.
+
+**Gate:** `go doc -all .` presents a coherent public contract, exported
+declarations have accurate comments, and contract tests protect every newly
+documented behavior whose compatibility risk warrants durable coverage.
+
+## Stage 3: Improve Consumer Safety And Executable Guidance
+
+Move consumer-relevant security boundaries to the places where consumers will
+encounter them and add one representative execution workflow.
+
+- [ ] Explain in public GoDoc and the consumer guide that the default file
+  artifact reader accepts unrestricted caller-selected paths.
+- [ ] Make clear that Promptkit does not impose an application root, inbound
+  request-size policy, or untrusted-input security boundary.
+- [ ] Explain that rendered messages, artifact bodies, raw model output, and
+  validation details may be sensitive even when credentials are redacted.
+- [ ] Clarify the responsibilities of injected artifact readers and model
+  clients for cancellation, copying, logging, and secret handling.
+- [ ] Add a maintained offline `Run` example using an injected deterministic
+  model client, without credentials, live network access, or paid calls.
+- [ ] Link the consumer guide to the execution example and keep embedded
+  snippets smaller than the maintained artifact.
+- [ ] Decide whether the existing preparation example should remain separate
+  or share reusable fixtures without obscuring either workflow.
+
+**Gate:** Both preparation and execution have complete, secret-free,
+deterministic consumer examples, and the consumer guide exposes the important
+filesystem and data-sensitivity boundaries without leaking internal mechanics.
+
+## Stage 4: Restore Canonical Ownership
+
+Remove parallel definitions and make navigation follow the ownership model in
+the documentation policy.
+
+- [ ] Reduce the [architecture policy](../policy/architecture.md) to durable
+  boundaries, layers, dependency direction, invariants, and non-goals.
+- [ ] Keep the exact implemented package and component inventory solely in the
+  [internal component overview](../internal/overview.md).
+- [ ] Review the consumer guide's public error and option lists so they remain
+  task-oriented summaries rather than duplicate API references.
+- [ ] Review internal documents for public-contract statements that should be
+  links to GoDoc or the format and integration owners.
+- [ ] Reconcile the documentation policy's temporary-roadmap lifecycle with
+  the continuing idea-catalog role of `docs/roadmap/future.md`.
+- [ ] Rephrase or link roadmap statements that depend on exact current API
+  behavior, particularly the runtime reasoning entry.
+- [ ] Confirm that every document states its audience or purpose and links to
+  the canonical owner of adjacent topics.
+
+**Gate:** Every authoritative fact has one clear owner, package inventory
+changes no longer require edits to the architecture policy, and roadmaps
+cannot be mistaken for current-state references.
+
+## Stage 5: Refine Format And Integration References
+
+Close compatibility gaps in the documents that own file formats and outbound
+wire behavior.
+
+- [ ] State or canonically link the exact session-ID limit enforced by the
+  OpenAI-compatible client.
+- [ ] State the configured and default transport-timeout behavior without
+  referring to an unnamed internal default.
+- [ ] Document the JSON Schema dialect and local, contained, and remote
+  reference behavior selected in Stage 1.
+- [ ] Clarify structured-output naming and strictness when those values are
+  part of the public or integration contract.
+- [ ] Add a caveat that built-in profiles are maintained configurations, not a
+  guarantee of continuing third-party model availability.
+- [ ] Recheck every prompt, profile, schema, credential, request-body, response,
+  timeout, and precedence statement against its owning implementation and
+  tests.
+
+**Gate:** A consumer can determine the supported file and wire compatibility
+boundaries without consulting internal source code or relying on unspecified
+defaults.
+
+## Stage 6: Make Documentation Validation Reproducible
+
+Align contributor and release procedures around a small, consistent set of
+checks.
+
+- [ ] Use one robust command for checking every tracked Go file with `gofmt`.
+- [ ] Provide a repository-local or clearly documented command that validates
+  local Markdown targets and heading fragments.
+- [ ] Decide how published external links are checked without making ordinary
+  validation depend on mutable network services.
+- [ ] Reconcile the validation descriptions in the
+  [development guide](../development.md),
+  [testing policy](../policy/testing.md), and
+  [release procedure](../release.md) so one document owns each requirement.
+- [ ] Ensure example validation covers every maintained example added by this
+  roadmap.
+- [ ] Keep documentation-only validation proportionate while requiring full Go
+  validation when commands, examples, generated output, or checked behavior
+  changes.
+
+**Gate:** A maintainer can run the documented formatting, link, example, Go,
+and repository-hygiene checks exactly as written, with no hidden manual
+procedure for local documentation.
+
+## Completion Criteria
+
+The roadmap is complete when:
+
+- all Stage 1 contract questions are resolved;
+- GoDoc is the authoritative and sufficient exported API reference;
+- consumer guidance covers unrestricted file access and sensitive generated
+  data;
+- maintained offline examples cover both `Prepare` and `Run`;
+- architecture, inventory, consumer, internal, format, integration, and
+  roadmap documents follow their assigned ownership boundaries;
+- schema, session, timeout, structured-output, and built-in-profile
+  compatibility statements are explicit;
+- documentation validation is reproducible and consistent across contributor
+  and release workflows; and
+- the complete maintainer validation passes.
+
+After completion, move any durable decisions to GoDoc, policy, format,
+integration, or ADR owners as appropriate. Remove this roadmap after incoming
+links are updated; do not retain it as a second current-state reference.

docs/roadmap/future.md

@@ -0,0 +1,122 @@
+# Future Feature Ideas
+
+## Purpose
+
+This document catalogs reasonably specific ideas that may be useful in future
+Promptkit development. It is an idea pool, not a commitment, schedule, or
+description of current behavior.
+
+Ideas belong here while they are worth retaining but have not been selected
+for active development. Keep each entry at the level of intended capability,
+consumer value, and important scope boundaries. Defer API design,
+implementation details, sequencing, and acceptance criteria until an idea is
+selected.
+
+## Using This Catalog
+
+- Add an idea when its purpose and likely value can be stated clearly.
+- Keep entries independent enough that maintainers can evaluate and select
+  them individually.
+- Note significant dependencies or boundary concerns, but do not turn entries
+  into implementation plans.
+- Treat inclusion as an invitation to evaluate, not as approval or priority.
+- When an idea is selected, move its active planning to a focused roadmap or,
+  when it requires a durable architectural decision, an ADR. Update
+  current-state documentation only when implementation lands.
+- Remove ideas that are no longer relevant. Retain a rejected idea only when
+  its rationale is likely to prevent repeated reconsideration.
+
+Future capabilities must continue to respect the
+[architecture policy](../policy/architecture.md), particularly Promptkit's
+role as an application-neutral library and its boundary with downstream
+consumers.
+
+## Ideas
+
+### Extensible LLM backend registry
+
+Introduce a registry that separates backend-specific connection,
+authentication, and limited request defaults from model execution profiles.
+Initial support would cover OpenAI-compatible backends and include a small
+built-in catalog, potentially starting with OpenRouter. A profile could select
+a backend while optionally overriding its default endpoint, and each backend
+could name an optional environment variable for its API key without storing
+the credential itself. Downstream consumers could register additional,
+uniquely named backends, such as OpenAI or unauthenticated local-network
+services, but could not replace built-in IDs. Model selection and generation
+settings would remain profile concerns, and custom model clients would remain
+available for behavior outside the registry's supported protocol.
+
+### Backend-specific concurrency management
+
+Extend the proposed LLM backend registry with optional per-backend concurrency
+limits and bounded, buffered admission queues. Promptkit could then route
+simultaneous generation requests according to backend capacity while
+containing accidental runaway submission. Downstream consumers would continue
+invoking synchronous `Run` calls, including concurrently from multiple
+goroutines, and each admitted call would wait for and return its ordinary
+result.
+
+- Scope limits to an engine instance rather than hidden process-global state.
+- Give different backend IDs independent capacity pools. A profile endpoint
+  override would remain part of its selected backend's pool.
+- Configure active concurrency and waiting capacity separately. Concurrency
+  protects the backend, while queue capacity protects the process from
+  admitting an unbounded backlog.
+- Give queue capacity a generous, configurable bounded default intended as a
+  safety ceiling for bugs or unintended loops rather than a routine
+  application constraint. Select an exact default during implementation
+  planning and measurement.
+- Reject a call with a recognizable capacity error when its backend queue is
+  full rather than allowing it to wait outside the bounded queue.
+- Admit requests before expensive preparation and artifact copying where
+  practical so queued work remains lightweight.
+- Apply a limit to each actual generation request, including repair attempts,
+  without unnecessarily serializing prompt preparation.
+- Make queued and active waits respect caller cancellation and deadlines.
+- Treat concurrency as backend policy rather than a profile-level model
+  setting.
+- Keep the queue ephemeral and in-process, with no survival guarantee across
+  engine or process shutdown.
+- Preserve the existing execution model as far as practical. Durable jobs,
+  polling, priorities, application worker lifecycle, retries, and
+  cross-process coordination would be separate future capabilities.
+
+### Explicit per-run session and reasoning controls
+
+Allow consumers to associate a session ID with each run and to inherit,
+replace, or explicitly disable the reasoning effort configured by its selected
+profile. Prompt definitions can currently derive a session ID from a template,
+and a non-empty runtime `ReasoningEffort` can replace the profile value, but
+there is no direct request-level session ID and an empty reasoning value means
+that no override was supplied. These controls would let consumers reuse one
+prompt and model profile across sessions and reasoning levels without
+maintaining duplicate definitions.
+
+- Preserve a prompt's session ID template and a profile's reasoning effort as
+  reusable defaults.
+- Let a directly supplied per-run session ID take precedence over a rendered
+  prompt default while retaining the existing validation limit and outbound
+  representation.
+- Distinguish an omitted runtime reasoning choice from an explicit request to
+  disable reasoning.
+- Ensure disabling reasoning omits the corresponding provider request setting
+  rather than relying on a provider-specific magic value.
+- Keep the effective session ID and reasoning choice visible in prepared and
+  run metadata and available to injected model clients without introducing
+  additional prompt or profile selection mechanisms.
+
+## Entry Format
+
+Use a short heading followed by a concise summary. Add focused bullets when
+they help preserve important scope boundaries without becoming an
+implementation plan:
+
+```markdown
+### Idea name
+
+Describe the intended capability, who benefits, and the most important scope
+boundary or dependency.
+
+- Optionally record an important behavior or boundary.
+```