docs(adr): codify promptfoo-first provider authoring

.agents/product-boundary.md

@@ -39,15 +39,16 @@ AgentV transcript artifacts are not Phoenix-native conversation inputs. Model-ca
 
 ## Promptfoo-Compatible Authoring Boundary
 
-AgentV should adopt Promptfoo-compatible eval matrix authoring where it strengthens repo-native evaluation, but Promptfoo is reference evidence rather than schema authority. The core mental model is `prompts x tests/vars x targets`, with repeat samples and retries applied as run policy after the authored matrix is resolved.
+AgentV adopts Promptfoo-compatible eval matrix authoring by default where Promptfoo has matching semantics. The core mental model is `prompts x tests/vars x providers`, with repeat samples and retries applied as run policy after the authored matrix is resolved.
 
 Keep these AgentV-native boundaries explicit:
 
-- `targets` are systems under test. A target `id` is stable AgentV identity; `provider` inside the target names the backend or adapter kind.
-- Top-level Promptfoo `providers` is not the canonical AgentV authoring key.
+- `providers` are systems under test. AgentV accepts Promptfoo-shaped provider declarations: strings like `openai:gpt-4.1-mini`, complete package provider strings like `package:@agentv/promptfoo-providers:CodexCliProvider`, provider option objects with `id`, `label`, `config`, `env`, `prompts`, `transform`, `delay`, and `inputs`, and provider maps like `{ "openai:gpt-4": { label, config } }`. In AgentV, `id` names the backend/spec and `label` is the stable AgentV identity used for selection and result grouping.
+- AgentV-only provider ids such as `agentv:codex-cli` are first-class AgentV authoring sugar, but they are not directly Promptfoo-runnable. `agentv export promptfoo` must lower supported built-ins to Promptfoo-readable `file://...:callApi` or complete `package:...:Export` provider entries.
 - Coding-agent testbeds use `environment` recipes for host/Docker substrate, setup, fixtures, services, and cwd. Do not make Promptfoo lifecycle `extensions` or public `workspace` authoring the canonical testbed contract.
+- Promptfoo export may lower a filesystem/host subset of `environment` into generated `extensions` plus provider workdir configuration. Docker environments are not part of the initial export subset and must fail with explicit diagnostics rather than silently losing isolation.
 - Top-level `env` means provider/eval environment variables. `extensions` remain lifecycle hooks.
-- Reusable prompts, tests, defaults, and environments use field-local `file://` refs such as `prompts: file://...`, `tests: file://...`, and `environment: file://...`.
+- Reusable prompts, tests, defaults, and environments use field-local `file://` refs such as `prompts: file://...`, `tests: file://...`, and `environment: file://...`. Export may rewrite supported AgentV refs into Promptfoo-readable generated files.
 - Grouping and Dashboard navigation use tags and run-bundle metadata, not experiment path buckets, Vercel path layout, or model-as-experiment grouping.
 - AgentV run bundles, traces, transcripts, datasets, indexes, and Git-backed artifacts stay AgentV-owned. Do not design an Opik export path or Phoenix projection path for those artifacts.
 
@@ -63,7 +64,7 @@ Prefer these extension points before adding a built-in:
 - plain assertion strings for simple semantic rubric checks
 - `llm-rubric` for promptfoo-compatible free-form rubric checks
 - `g-eval` for structured or multi-criteria rubric judging
-- config-level grader targets selected through `defaults.grader` or assertion-level target selection, not target-level grader configuration
+- config-level grader providers selected through `defaults.grader` or assertion-level provider selection, not system-under-test provider configuration
 - CLI wrappers that consume AgentV JSON or JSONL output for post-processing such as aggregation, comparison, or reporting
 
 Ask: can this be achieved with existing primitives plus a plugin or wrapper? If yes, it should not be a built-in. That includes niche config overrides for existing graders.
@@ -107,7 +108,7 @@ Research those references from local cloned repositories first when a clone is a
 
 Treat these as reference inputs, not dependencies. AgentV should adopt the shared lowest common denominator when it fits the repo-native artifact model, and document any intentional divergence in the relevant plan, ADR, or contract docs.
 
-Do not copy another framework's schema baggage just because the framework is credible. When a peer contract carries historical constraints, overloaded field names, or compatibility aliases, prefer a cleaner AgentV contract if it preserves the core user need. Document the reason for diverging so future workers do not "realign" it back to the peer shape. For target/provider contracts, keep identity and backend/control boundary separate: use a stable AgentV `id` for the target registry key when `provider` already names the adapter/backend kind. Promptfoo's `label` is useful evidence but should not be copied as target identity merely because Promptfoo uses `id` for provider/backend specs.
+Do not copy another framework's schema baggage just because the framework is credible. When a peer contract carries historical constraints, overloaded field names, or compatibility aliases, prefer a cleaner AgentV contract if it preserves the core user need. Document the reason for diverging so future workers do not "realign" it back to the peer shape. For the provider surface, ADR 0019 is the current exception: AgentV follows Promptfoo's `providers`/`id`/`label` shape so the uncommon AgentV differences stay concentrated in `environment`, refs, built-in AgentV providers, artifacts, and Dashboard behavior.
 
 ### 5. YAGNI - You Aren't Gonna Need It
 

AGENTS.md

@@ -14,10 +14,11 @@ AgentV aims to be the repo-native, workspace-native evaluation framework for AI
 
 Eval authoring mental model:
 
-- AgentV adopts Promptfoo-compatible matrix authoring where it helps: an eval expands `prompts x tests/vars x targets`, then applies repeat samples/retries as run policy. This is compatibility by composition, not a wholesale copy of Promptfoo's schema.
-- Author systems under test as `targets`. A target `id` is the stable AgentV identity; `provider` inside the target names the backend or adapter kind. Top-level Promptfoo `providers` is reference evidence, not the canonical AgentV authoring key.
-- Use `environment` recipes for coding-agent testbeds, including host/Docker setup, repo materialization, fixtures, services, and cwd. Do not use Promptfoo `extensions` or public `workspace` authoring as the canonical testbed contract.
-- Use top-level `env` for provider/eval environment variables. Use `extensions` for lifecycle hooks. Use field-local `file://` refs for reusable prompts, tests, defaults, and environments.
+- AgentV adopts Promptfoo-compatible matrix authoring by default: an eval expands `prompts x tests/vars x providers`, then applies repeat samples/retries as run policy.
+- Author systems under test as `providers`. A provider entry `id` names the backend/spec string; `label` is the stable AgentV selection and result identity. `id` may contain Promptfoo-style colons such as `openai:responses:gpt-5.4`.
+- The intended authored-config differences from Promptfoo are limited to `environment`, AgentV refs, and built-in AgentV providers such as `agentv:codex-cli`. Full Promptfoo compatibility for those AgentV-native pieces is by `agentv export promptfoo`.
+- Use `environment` recipes for coding-agent testbeds, including host/Docker setup, repo materialization, fixtures, services, and cwd. Promptfoo export may lower a host/filesystem subset into generated `extensions` plus provider workdir configuration; Docker environments must remain unsupported on export until a faithful runner boundary exists. Do not use Promptfoo `extensions` or public `workspace` authoring as the canonical AgentV testbed contract.
+- Use top-level `env` for provider/eval environment variables. Use `extensions` for lifecycle hooks. Use field-local `file://` refs for reusable prompts, tests, defaults, and environments; export may rewrite supported AgentV refs into Promptfoo-readable files.
 - Use `tags` and run-bundle metadata for grouping and Dashboard navigation. Do not use experiment path buckets, Vercel path layout, or model-as-experiment grouping as canonical AgentV semantics.
 - AgentV run bundles, traces, transcripts, datasets, indexes, and Git-backed artifacts stay AgentV-owned. Do not design an Opik export path or Phoenix projection path for them; Phoenix correlation is link-out only when `external_trace` metadata already exists.
 
@@ -39,20 +40,21 @@ tests:
       issue: "Explain the flaky retry behavior"
       repo: "file://fixtures/retry"
 
-targets:
-  - id: codex-host
-    provider: codex-cli
+providers:
+  - id: agentv:codex-cli
+    label: codex-host
     runtime: host
-  - id: claude-docker
-    provider: claude-cli
-    runtime: docker
+    config:
+      command: codex
+  - id: anthropic:claude-agent-sdk
+    label: claude
 
 environment: file://.agentv/environments/local-repo.yaml
 tags:
   experiment: prompt-compare
 ```
 
-This produces eight authored target-case executions before repeat policy: 2 prompts x 2 `tests[].vars` cases x 2 targets.
+This produces eight authored provider-case executions before repeat policy: 2 prompts x 2 `tests[].vars` cases x 2 providers.
 
 Phoenix boundary after the 2026-06-20 product decision:
 
@@ -68,7 +70,7 @@ Design guardrails:
 - Document composition patterns before inventing a new feature.
 - Match industry-standard lowest-common-denominator contracts when possible.
 - When designing AgentV contracts, check public reference standards such as Claude Skills, Vercel agent-eval, Hugging Face Datasets, and OpenInference before inventing AgentV-specific shapes. Use their shared lowest common denominator where it fits, and document any intentional divergence.
-- Treat peer frameworks as evidence, not schema authority. Do not inherit baggage such as overloaded field names, compatibility aliases, or framework-specific historical constraints when AgentV can express a cleaner repo-native contract. Example: prefer `id` for stable AgentV target identity when `provider` already names the backend/control boundary, even if Promptfoo uses `label` because its `id` field is overloaded as a provider spec.
+- Treat peer frameworks as evidence, not schema authority. Do not inherit baggage such as overloaded field names, compatibility aliases, or framework-specific historical constraints when AgentV can express a cleaner repo-native contract. For the provider surface, AgentV intentionally follows Promptfoo's `providers`/`id`/`label` shape so the uncommon AgentV differences stay concentrated in `environment`, refs, built-in AgentV providers, artifacts, and Dashboard behavior.
 - For peer-framework research, use local cloned repositories and DeepWiki MCP before broad web search. In this operator workspace, Promptfoo is cloned at `/home/entity/projects/promptfoo/promptfoo` and DeepEval is cloned at `/home/entity/projects/confident-ai/deepeval`; use DeepWiki repos `promptfoo/promptfoo` and `confident-ai/deepeval` for architecture-level orientation, then verify exact claims with `rg` and `git` in the local clone. If a public contract must be checked for currentness, use official docs and record the source URL or clone commit behind the conclusion.
 - Apply YAGNI aggressively and solve the current request with the smallest surface that works.
 - Keep extensions non-breaking unless a same-week unreleased surface should be hard-corrected.