docs: define domain-intelligence query architecture

docs/adr/0017-domain-intelligence-query-contract.md

@@ -0,0 +1,75 @@
+# ADR-0017: Domain-intelligence query contract
+
+- Status: Proposed
+- Date: 2026-09-14
+- Related: [Issue #323](https://github.com/wrightkit/wright/issues/323), [ADR-0010](0010-independent-implementations-and-wright-integration.md), [ADR-0015](0015-canonical-facts-and-declarative-lint-policy.md)
+
+## Context
+
+Wright already exposes shared query/tooling services for CLI, embedding, and transport consumers. Its `targetMetadata` operation is a broad catalog summary, while ADR-0015 separates owner-backed canonical facts from Wright lint/policy behavior.
+
+Agent workflows need a narrower capability: given the semantic construct currently being worked on, retrieve only the relevant Workshop facts, source-owner context, and practical guidance. Serving that through static prompts or copied metadata would duplicate semantic authority, make provenance ambiguous, and force each consumer to implement its own lookup behavior.
+
+The design must also support human-authored best practices without allowing guidance to become an implicit correctness specification.
+
+## Decision
+
+Wright adds one product-level domain-intelligence composition contract with these rules:
+
+1. **The service is a query, not a semantic store.** Canonical Workshop facts and identities are resolved from `workshop-rs`; source-language meaning is resolved by the source owner. Wright owns composition and presentation.
+2. **Selection is semantic and bounded.** A request selects canonical owner identities directly, or supplies a source location that an owning implementation/provider resolves to semantic subjects. Wright does not fall back to textual guessing when source resolution is unavailable.
+3. **Canonical lookup is project-independent.** Direct canonical selection must work without an eagerly loaded source project. Source-position selection may require project/provider state because source resolution is owner-dependent.
+4. **The public information model stays simple.** Returned domain-intelligence items use `fact`, `warning`, or `info`. `fact` is owner-backed factual information; `warning` and `info` are Wright-curated guidance at different levels of attention. These are domain-intelligence presentation classes, not lint/diagnostic severity.
+5. **Provenance is explicit without imposing a public evidence taxonomy.** Each item identifies its responsible owner or guidance source and carries traceable references where available. Consumers are not required to understand a separate enum for runtime evidence, heuristics, or community guidance, and Wright does not synthesize numeric confidence scores.
+6. **Built-in guidance is curated by Wright.** The initial corpus is first-party Wright guidance with stable identity, semantic applicability, provenance, and limitations where needed. Human guidance cannot self-promote to canonical semantics.
+7. **External guidance sources are deferred.** Community or project-configured guidance may be added later only after a concrete contract defines trust, provenance, conflict, and update behavior. The initial design does not add a project-policy overlay or arbitrary guidance loading.
+8. **All product consumers reuse the same operation.** `domainIntelligence` belongs on Wright's common query/tooling surface. CLI, embedding, stdio/JSON-RPC, and future agent adapters remain thin consumers of that contract.
+9. **The change is additive to the existing v1 embedding/result compatibility rules.** A new major contract version is not required solely to add the operation.
+10. **LPP is not extended pre-emptively.** Provider-backed source selection may expose a future protocol gap; until evidence requires a wire capability, unsupported source selection is reported explicitly rather than forcing a speculative LPP extension.
+
+`targetMetadata` remains a broad target/catalog discovery summary and is not repurposed as the domain-intelligence operation.
+
+## Alternatives considered
+
+- **Reuse `targetMetadata` and add more fields:** rejected because a bulk catalog response does not express semantic selection, source-owner resolution, or provenance-bearing guidance, and would trend toward a monolithic agent payload.
+- **Require a loaded project/session for every query:** rejected because canonical Workshop facts and built-in guidance are useful without source-project context; only source-position resolution inherently needs owner/project state.
+- **Expose a detailed public evidence taxonomy:** rejected because consumers primarily need a clear fact-versus-guidance distinction and provenance. Runtime/community/heuristic detail can remain source metadata where useful without becoming the main product model.
+- **Copy Workshop facts into Wright guidance assets:** rejected because it creates a shadow semantic authority that can drift from `workshop-rs`.
+- **Put best-practice guidance in `workshop-rs`:** rejected because product guidance is not canonical Workshop semantics.
+- **Accept arbitrary community/project guidance in v1:** deferred because the system does not yet define trust, provenance, conflict, or update behavior for external sources. Wright curates the initial built-in corpus while keeping the item contract open to future sources.
+- **Add project-policy suppression/ranking in v1:** rejected because there is no current consumer requirement for a domain-intelligence policy overlay; lint policy should not be generalized into this product surface without evidence.
+- **Create a general knowledge database, plugin runtime, or package manager first:** rejected because no current consumer evidence requires those mechanisms and they add independent versioning/distribution concerns.
+- **Extend LPP first:** deferred because canonical identity queries and in-process owner integrations do not require a new wire method; a provider protocol change should follow an observed provider-backed source-selection need.
+- **Embed prompt-ready text in Wright core:** rejected because prompt formatting is consumer presentation, while the durable contract should remain structured and reusable across CLI, embedding, and other agents.
+
+## Consequences
+
+- Agents can request small, context-specific payloads instead of loading the entire Workshop knowledge surface.
+- Canonical facts remain owned and updated where their semantics live.
+- Simple `fact` / `warning` / `info` presentation keeps the agent-facing contract understandable while provenance preserves traceability.
+- Canonical lookups can serve reference-style workflows without requiring a source project.
+- Wright can evolve a curated guidance corpus without creating a second Workshop semantic authority.
+- Source-owner capability gaps remain visible rather than being hidden by Wright text heuristics.
+- Implementation must add a public operation/result shape and provide contract tests across the shared query surface and transport adapters.
+- A provider-backed source selector may later require a separate LPP decision, but that work is not required by this ADR.
+
+## Compatibility impact
+
+The decision adds a new public query operation without changing source-language syntax, Workshop semantics, compiler lowering, diagnostics, or existing query behavior. Under the current embedding/result versioning rules, adding the operation is compatible within major version 1.
+
+Implementation evidence must show that direct/in-process and transport consumers observe the same structured result, direct canonical queries do not require unnecessary project loading, owner facts are not duplicated as Wright authority, and unavailable owner capabilities are surfaced explicitly.
+
+## Scope boundaries
+
+This ADR does not decide:
+
+- the storage path or serialization syntax used to author first-party guidance;
+- community/project guidance source loading or remote guidance distribution;
+- registries or executable plugins;
+- project-specific suppression/ranking policy for guidance;
+- prompt templates or token-cache optimization;
+- a new LPP method for semantic selection;
+- automatic source edits based on guidance;
+- whether every source-language construct can map to a canonical Workshop identity.
+
+Those decisions require separate concrete consumer or provider evidence.

docs/adr/README.md

@@ -36,4 +36,5 @@ audit date.
 * [ADR-0014: Repository-namespaced immutable R2 release artifacts](0014-namespaced-immutable-r2-artifacts.md)
 * [ADR-0015: Canonical facts, declarative lint rules, and project policy](0015-canonical-facts-and-declarative-lint-policy.md)
 * [ADR-0016: Current-directory and directory project targets](0016-current-directory-and-directory-project-targets.md)
+* [ADR-0017: Domain-intelligence query contract](0017-domain-intelligence-query-contract.md)
 * [Post-ADR-0010 decision inventory](post-0010-inventory.md)

docs/architecture/README.md

@@ -16,6 +16,7 @@ Keep these evidence classes separate:
 | Product/repository ownership and dependency direction | [`ownership.md`](ownership.md) |
 | Language/provider integration and failure routing | [`integration.md`](integration.md) |
 | Wright-owned lint/analyze/inspect/edit/agent/CI/LSP tooling model | [`tooling.md`](tooling.md) |
+| On-demand Workshop domain intelligence for agent/embedding consumers | [`domain-intelligence.md`](domain-intelligence.md) |
 | CLI/driver behavior | [`../cli.md`](../cli.md) |
 | Embedding/tool API | [`../embedding.md`](../embedding.md) |
 | Language services/LSP | [`../language-services.md`](../language-services.md) |

docs/architecture/domain-intelligence.md

@@ -0,0 +1,103 @@
+# Wright Domain Intelligence Contract
+
+Wright exposes Workshop domain intelligence as a composed query over existing semantic owners. It does not own a second Workshop catalog or a source-language semantic model.
+
+Decision history: [ADR-0017](../adr/0017-domain-intelligence-query-contract.md).
+
+## Purpose
+
+Agent, CLI, embedding, and transport consumers need bounded context about the semantic construct they are working with: canonical Workshop facts, relevant source-language context, and practical guidance. They obtain that context through one Wright-owned query contract instead of loading a monolithic prompt or reimplementing owner lookups.
+
+## Ownership
+
+| Information class | Authority |
+| --- | --- |
+| Canonical Workshop identities, signatures, settings, localization, gameplay facts, and other Workshop semantics | `workshop-rs` |
+| OverPy syntax/semantic context and mapping from OverPy source constructs | `opy-rs` |
+| DEL/OSTW syntax/semantic context and mapping from DEL/OSTW source constructs | `deltin-rs` |
+| Domain-intelligence query composition, public result contract, built-in guidance curation, and product presentation | Wright |
+| Built-in human-authored guidance | Wright-curated first-party corpus; it remains guidance rather than semantic authority |
+
+A guidance item may refer to a canonical Workshop identity, but it must not restate copied catalog data as an independent authority. If a canonical fact is needed, the query resolves it from its owner.
+
+External or project-configured guidance sources are not part of the initial contract. A future source/distribution contract may add them without changing canonical ownership, but Wright does not accept arbitrary guidance sources until trust, provenance, conflict, and update behavior are defined.
+
+## Selection
+
+A domain-intelligence request selects a bounded semantic subject through one of two forms:
+
+1. **Canonical selection** supplies one or more opaque canonical identities issued by the owning Workshop contract. Localized display names are not identities. Canonical selection does not require a loaded source project.
+2. **Source selection** supplies a language ID plus source/document identity and position. Wright delegates semantic resolution to the owning implementation or configured provider and composes the returned canonical subject references with any owner-supplied source context. Source selection requires the relevant project/provider context.
+
+Wright must not infer a source selection with textual matching when the owner cannot resolve it. Missing owner capability is an explicit unavailable result.
+
+The logical request shape is:
+
+```text
+DomainIntelligenceRequest
+  selector = Canonical([SemanticRef...])
+           | Source(language_id, document, position)
+  include  = items | source_context
+```
+
+`include` is a projection over the selected subjects. The service does not return the complete guidance corpus or catalog by default.
+
+## Response model
+
+The shared result is structured rather than prompt text:
+
+```text
+DomainIntelligenceResult
+  subjects[]
+  items[]
+  source_context[]
+  unavailable[]
+```
+
+Each subject carries its owner, semantic kind, canonical or owner-specific identity, and presentation metadata when available. Wright may join information by stable owner identity, but it does not invent a cross-language semantic identity when no owner mapping exists.
+
+Each `item` has one simple public classification:
+
+- `fact`: owner-backed factual information about the selected semantic subject;
+- `warning`: Wright-curated guidance about a meaningful risk, cost, or behavior that commonly deserves attention;
+- `info`: Wright-curated recommendation, usage pattern, caveat, or explanatory context.
+
+These classifications are domain-intelligence presentation semantics, not lint/diagnostic severity. A `fact` is not an error, and `warning`/`info` guidance does not become a correctness diagnostic merely because it is returned by the query.
+
+Facts remain machine-readable where the owner exposes structured data. Guidance has a stable guidance ID, applicability to semantic subjects, provenance, limitations when needed, and human-readable content. Guidance remains independently editable from canonical facts.
+
+`source_context` contains source-owner information needed to explain how the selected source construct relates to the subject. Wright standardizes the envelope and provenance, not the source language's internal semantic model.
+
+`unavailable` reports missing owner capability or unavailable source context explicitly. Wright does not guess a replacement fact or silently downgrade to text matching.
+
+## Provenance
+
+Every returned item identifies its responsible owner or guidance source and carries a traceable locator or evidence reference where one exists.
+
+The public query contract does not require consumers to understand a detailed evidence taxonomy such as runtime evidence, heuristic, or community guidance, and it does not assign synthetic numeric confidence scores. Richer evidence metadata may exist in the owning fact source or guidance corpus for curation and review, but it does not replace the simple `fact` / `warning` / `info` contract.
+
+Human-authored guidance cannot self-promote to a canonical fact. Provenance must remain sufficient to tell owner-backed facts from Wright-curated guidance.
+
+## Public service boundary
+
+The shared product operation is `domainIntelligence` on Wright's common query/tooling surface. CLI, embedding, stdio/JSON-RPC, and future agent adapters reuse that operation rather than creating agent-specific semantics.
+
+The operation may be exposed through the existing ToolService facade, but canonical selection must not require an eagerly loaded project session. Source selection may use session/provider state because resolving source positions is inherently project- and owner-dependent.
+
+The operation is additive within the existing `wright-embedding/v1` / `wright-result/v1` compatibility rules. Adding it does not require a new major contract version; removing or incompatibly changing its declared fields does.
+
+Existing `targetMetadata` remains a catalog/discovery summary. It is not the domain-intelligence contract because it exposes broad target metadata rather than a selected, provenance-bearing composition of facts and guidance.
+
+## Provider boundary
+
+This contract does not require LPP to grow a source-selection method before evidence demands it. An in-process owner or provider may support source selection through an owner-backed semantic query. If a configured provider cannot resolve a source position to semantic subjects, Wright returns the capability gap explicitly.
+
+A future LPP source-selection capability is a separate protocol decision and must preserve the same ownership rule: the provider resolves source-language meaning; Wright composes product context.
+
+## Guidance boundary
+
+The initial built-in guidance corpus is curated by Wright. Guidance is human-authored content plus machine-readable identity, semantic applicability, provenance, and limitations where needed. Its storage syntax and distribution mechanism are not semantic contracts and may evolve without moving canonical Workshop facts into Wright.
+
+This initial ownership choice does not require all future guidance to be authored by Wright. Additional community or project guidance sources may be added later if a concrete source/distribution contract defines trust, provenance, conflict, and update behavior.
+
+Wright does not require a package manager, executable plugin runtime, remote knowledge database, project-policy overlay, or prompt template to serve the initial contract. Those mechanisms require separate evidence and decisions.

docs/architecture/tooling.md

@@ -3,9 +3,11 @@
 Wright owns cross-language product tooling over semantic information supplied by the owning implementations and canonical Workshop.
 
 Decision history: the distinct command workflows are recorded in
-[ADR-0011](../adr/0011-distinct-tooling-workflows.md), and the canonical-facts
+[ADR-0011](../adr/0011-distinct-tooling-workflows.md), the canonical-facts
 and lint-policy split is recorded in
-[ADR-0015](../adr/0015-canonical-facts-and-declarative-lint-policy.md).
+[ADR-0015](../adr/0015-canonical-facts-and-declarative-lint-policy.md), and
+on-demand domain-intelligence composition is recorded in
+[ADR-0017](../adr/0017-domain-intelligence-query-contract.md).
 
 ## Tooling surfaces
 
@@ -51,6 +53,8 @@ Normal source tooling does not require full-file regeneration. Preserve comments
 
 CLI, LSP, agent/MCP-style adapters, embedding, and CI should reuse common Wright-owned semantic/query/edit services rather than each implementing language-specific logic independently.
 
+On-demand domain intelligence follows the same rule: Wright composes owner-backed semantic identities and facts with separately provenance-bearing Wright-curated guidance through the shared query surface. Direct canonical queries do not require source-project state; source-position queries may use project/provider context. Wright does not copy canonical Workshop facts into an agent-specific knowledge store. See [`domain-intelligence.md`](domain-intelligence.md).
+
 Machine-readable contracts are versioned and deterministic when declared. Presentation layers must not alter semantic outcomes.
 
 ## Lint and analysis evidence