docs: define governed refund paid pilot (#21)

Co-authored-by: fly1d <fly1d@users.noreply.github.com>

Author: fly1d

CHANGELOG.md

@@ -15,3 +15,4 @@ for public contracts once they are declared stable.
 - Human approval queue with single-decision enforcement and append-only audit events.
 - PostgreSQL system of record with transactional audit writes, Alembic migrations, readiness
   checks, and database-level audit mutation protection.
+- Reproducible governed-refund demo, paid-pilot boundary, and customer-discovery criteria.

Makefile

@@ -12,7 +12,7 @@ lint:
 	python -m ruff check .
 
 type:
-	python -m mypy src
+	python -m mypy src examples
 
 unit:
 	python -m pytest tests/unit --cov=agent_control_plane --cov-report=term-missing

README.md

@@ -25,6 +25,19 @@ Not in the initial scope:
 - a replacement for Temporal, Mem0, LangSmith, or DSPy;
 - Kubernetes before workload and isolation requirements justify it.
 
+## First validation scenario
+
+The initial commercial hypothesis is governed refund approval for an existing customer-support
+agent. The repository includes a reproducible end-to-end demo, a bounded paid-pilot offer, and a
+customer-discovery guide:
+
+- [`examples/refund_approval.py`](examples/refund_approval.py)
+- [`docs/PAID_PILOT.md`](docs/PAID_PILOT.md)
+- [`docs/CUSTOMER_DISCOVERY.md`](docs/CUSTOMER_DISCOVERY.md)
+
+These are validation materials, not a production-readiness claim. Major provider integrations
+remain deferred until customer evidence identifies a concrete blocker.
+
 ## Quick start
 
 Requirements: Python 3.11 or newer.

docs/CUSTOMER_DISCOVERY.md

@@ -0,0 +1,66 @@
+# Customer Discovery
+
+The purpose of discovery is to falsify or support the paid-pilot hypothesis in
+`docs/PAID_PILOT.md`. It is not a product pitch and should not be used to manufacture positive
+feedback.
+
+## Recruitment
+
+Interview people responsible for an agent already used in customer support, finance operations,
+security operations, or another workflow with consequential tool calls. Prioritize the
+engineering owner, the operator who handles exceptions, and the person accountable for risk or
+budget. Avoid counting people who are only exploring agents and have no deployed workflow.
+
+Do not put customer names, personal data, credentials, incident details, or confidential logs in
+this public repository. Store interview notes in an approved private system and use anonymous
+identifiers in aggregate results.
+
+## Thirty-minute interview
+
+Spend the first 20 minutes on past behavior before showing the demo.
+
+1. What agent workflow is running today, and who owns it when something goes wrong?
+2. Tell me about the last incorrect or risky action. What happened next?
+3. Which actions require a person to review them today? Walk through the actual process.
+4. How often are actions delayed, repeated, silently dropped, or approved without enough context?
+5. How do you determine which agent, prompt, tool call, and person caused an outcome?
+6. When did you last pause or roll back an agent? How long did diagnosis and recovery take?
+7. What does the current process cost in engineering time, operator time, refunds, or risk?
+8. Which controls are mandatory before this workflow can handle more volume?
+9. Who owns the budget for fixing this, and what has already been purchased or built?
+10. Is there a time-bound project where a three-week staging pilot could be evaluated?
+
+Then show the refund-approval scenario. Ask what would have to change for it to fit their actual
+workflow, which evidence is missing, who else must approve a pilot, and what decision date is
+realistic. Do not ask whether they "like" the product or whether they "would use" it someday.
+
+## Evidence record
+
+Record one row per interview outside the public repository:
+
+| Field | Evidence to capture |
+| --- | --- |
+| Segment | Industry, team function, and deployed-agent maturity |
+| Last incident | Date range, failure type, impact, and current recovery path |
+| Frequency | Consequential actions and manual reviews per week |
+| Current spend | Tools plus engineering and operator effort |
+| Required control | Approval, audit, pause, replay, evaluation, or another named need |
+| Buying process | Budget owner, security owner, procurement steps, and deadline |
+| Commitment | Introduction, data sample, technical session, trial, or paid pilot |
+| Disconfirming evidence | Reason the problem is unimportant or already solved |
+
+Separate direct quotes and observed behavior from interpretation. A verbal compliment is not a
+commitment; access to a technical owner, sanitized cases, scheduled integration time, or payment
+is progressively stronger evidence.
+
+## Decision thresholds
+
+Run 20 qualified interviews before broadening the product. Continue toward the refund pilot if
+at least eight teams report the problem from recent experience, five provide a technical follow-
+up or representative cases, two commit engineering time to an evaluation, and one signs a paid
+pilot within eight weeks.
+
+Stop or change the segment if fewer than five teams report a recent consequential failure, the
+problem has no named budget owner, or existing observability and workflow tools already solve it
+without meaningful friction. Build Mem0, DSPy, Temporal, or another major adapter only when
+repeated interview and pilot evidence identifies that capability as the blocker.

docs/PAID_PILOT.md

@@ -0,0 +1,88 @@
+# Paid Pilot: Governed Refund Approvals
+
+This document defines a commercial hypothesis to test, not a claim that the current project is
+production-ready or that demand has already been proven.
+
+## Buyer and problem
+
+The initial buyer is the engineering or risk owner of a customer-support agent that can propose
+refunds or credits. Their problem is not generating another answer. It is proving that a risky
+action waited for the right human decision, preserving who decided it and why, and recovering
+when an agent version behaves badly.
+
+The qualifying scenario has all of these properties:
+
+- an agent already runs in a test or production workflow;
+- at least one action can create financial, compliance, or customer harm;
+- humans review some of those actions today, even if the process is manual;
+- the team cannot reconstruct decisions quickly from its current logs;
+- a named owner has budget or authority to sponsor an operational pilot.
+
+## Offer
+
+The starting commercial hypothesis is a three-week, CNY 30,000 paid pilot in an isolated or
+staging environment. Taxes, travel, custom infrastructure, and production support are outside
+that price. Any quote to a real buyer must state the exact deployment boundary and data policy.
+
+The pilot covers:
+
+- one existing customer-support agent;
+- one high-risk refund or credit action;
+- registration, pause/activate, approval, decision, and audit integration;
+- one policy workshop and one operator handoff session;
+- a final evidence report against the agreed metrics.
+
+The customer continues to own agent reasoning and execution. The control plane records and
+governs the action request; it does not move money. No custom dashboard, compliance
+certification, 24/7 SLA, model hosting, Mem0, DSPy, or autonomous prompt changes are included.
+
+## Acceptance metrics
+
+Before integration, both parties choose a representative set of at least 20 synthetic or
+sanitized refund cases. The pilot succeeds technically when:
+
+- every above-threshold test action is held until an explicit decision;
+- every sampled decision can be reconstructed from actor, reason, status, and audit events;
+- stale lifecycle writes and repeated decisions fail closed;
+- the customer can pause the integrated agent and observe the state change;
+- the integration requires no more than five customer engineering days.
+
+Commercial validation is separate from technical success. Continue investing after the pilot
+only if a named buyer agrees the problem is material, uses the workflow with real operators, and
+offers a paid production next step. Do not treat repository stars, compliments, or an unpaid
+demo as purchase evidence.
+
+## Readiness boundary
+
+The current `main` branch is suitable for local and isolated evaluation. A pilot using
+customer-accessible infrastructure must wait for authentication in issue #15 and pull request
+#16 to receive the required independent security reviews. Production use additionally requires
+idempotency, backup and restore rehearsal, tenant/resource authorization, token rotation or
+OIDC, rate limiting, and an agreed operational owner.
+
+## Demo
+
+Start the development API and run the reproducible scenario from another shell:
+
+```bash
+make run
+python examples/refund_approval.py
+```
+
+The script registers a uniquely named support agent, activates it, requests approval for a CNY
+1,280 refund, verifies that the request is pending, records a human decision, and checks the four
+audit events. It does not call a payment or refund system.
+
+For an authenticated environment, configure a bearer token for each principal:
+
+```bash
+export ACP_DEMO_OPERATOR_TOKEN='<operator-token>'
+export ACP_DEMO_AGENT_TOKEN='<agent-token>'
+export ACP_DEMO_REVIEWER_TOKEN='<reviewer-token>'
+python examples/refund_approval.py
+```
+
+The subjects configured for those tokens must match `ACP_DEMO_OPERATOR_ACTOR`,
+`ACP_DEMO_AGENT_ACTOR`, and `ACP_DEMO_REVIEWER_ACTOR`. `ACP_DEMO_TOKEN` is a convenience fallback
+only when all three actor variables are also set to that token's subject. Separate
+least-privilege identities are required for a real pilot.

examples/__init__.py

@@ -0,0 +1 @@
+"""Executable product scenarios for evaluating Agent Control Plane."""